VBA and jsdoc

For an overview of what VbaGit is, please read Integrate VBA with Github. If you are working with Google Apps Script as well as VBA, then you will probably be familiar with JDSOC. This is a way of documenting your code in order to generate automatic documentation. 


Some of what JSDOC does is already done by the automatic documentation feature in VbaGit (example). I figured it would be nice if VbaGit could enhance that by understanding a subset of JSDOC. That means that you can copy documentation for functions between VBA and Apps Script versions of things without having to rewrite them. VbaGit will take JSDOC syntax and build it into the markdown documentation it creates - see the example below of the docs generated for a procedure.


The argument and return types are detected from analyzing the code, but the description of the procedure and its arguments are taken from any JSDOC type comments that VbaGit finds in the code. 

In JavaScript, the above would be documented like this

/**
 * do the import from github and replace the modules in the companion workbook
 * @param {string} repoName the github reponame
 * @param {string} projectName the vbaproject name
 * @param {boolean} applyExcelReferences whether to apply the excel references in dependency list
 * @return {void}
 */

Of course this is not valid syntax in VBA, but all we have to do is comment out the block, and leave it in the code just before the procedure to which it applies

'/**
' * do the import from github and replace the modules in the companion workbook
' * @param {string} repoName the github reponame
' * @param {string} projectName the vbaproject name
' * @param {boolean} applyExcelReferences whether to apply the excel references in dependency list
' * @return {void}
' */

the @return and {..type..} constructs are ignored by VbaGit since it can accurately get those from the code analysis, but you can leave them in if you like, or miss out the @return and leave the type construct as {}, so this will work equally well

'/**
' * do the import from github and replace the modules in the companion workbook
' * @param {} repoName the github reponame
' * @param {} projectName the vbaproject name
' * @param {} applyExcelReferences whether to apply the excel references in dependency list
' */

and that's it!

Now take a look below for more on this subject

For help and more information join our communityfollow the blog or follow me on twitter . For how to do this for Google Apps Script, see Getting your apps scripts to Github

You want to learn Google Apps Script?

Learning Apps Script, (and transitioning from VBA) are covered comprehensively in my my book, Going Gas - from VBA to Apps script, available All formats are available now from O'Reilly,Amazon and all good bookshops. You can also read a preview on O'Reilly

If you prefer Video style learning I also have two courses available. also published by O'Reilly.
Google Apps Script for Developers and Google Apps Script for Beginners.



Comments