Solved VBA Code Documentation Tools (1 Viewer)

[Josef P.]

I am in the process of revising my reusable code modules. This also includes the documentation of the interfaces.

Currently I use code comments that can be evaluated with doxygen. Unfortunately these are not very readable in the code.

Doxygen
URL: https://www.doxygen.nl/

Example:

'---------------------------------------------------------------------------------------
' Function: BuildCriteria
'---------------------------------------------------------------------------------------
'/**
' <summary>
' Create SQL criteria string
' </summary>
' <param name="FieldName">Field name in the data source to be filtered</param>
' <param name="RelationalOperator">Relational operator (=, <=, etc.)</param>
' <param name="FilterValue">Filter value (can be a single value or an array of values)</param>
' <param name="FilterValue2">Optional 2nd filter value (for Between)</param>
' <param name="IgnoreValue">The value for which no filter condition is to be created. (Array transfer of values possible)</param>
' <returns>SQL criteria string</returns>
' <remarks>
' </remarks>
'**/
'---------------------------------------------------------------------------------------
Public Function BuildCriteria(ByVal FieldName As String, ByVal FieldDataType As SqlFieldDataType, _
                              ByVal RelationalOperator As SqlRelationalOperators, _
                              ByVal FilterValue As Variant, _
                     Optional ByVal FilterValue2 As Variant = Null, _
                     Optional ByVal IgnoreValue As Variant, _
                     Optional ByVal DisableIgnoreNullValue As Boolean = False) As String
...

Result as HTML:

• Homepage
• SqlTools CodeModule

Some time ago I discovered Natural Docs.
Does anyone use it?
It makes the comment in the code much easier to read.

Natural Docs
URL: https://www.naturaldocs.org/

Example:

'---------------------------------------------------------------------------------------
' Function: BuildCriteria
'---------------------------------------------------------------------------------------
'
' Create SQL criteria string
'
' Parameters:
'     FieldName            - Field name in the data source to be filtered
'     RelationalOperator   - Relational operator (=, <=, etc.)
'     FilterValue          - Filter value (can be a single value or an array of values)
'     FilterValue2         - Optional 2nd filter value (for Between)
'     IgnoreValue          - The value for which no filter condition is to be created. (Array transfer of values possible)
'
' Returns:
'     SQL criteria string
'
'---------------------------------------------------------------------------------------
Public Function BuildCriteria(ByVal FieldName As String, ByVal FieldDataType As SqlFieldDataType, _
                              ByVal RelationalOperator As SqlRelationalOperators, _
                              ByVal FilterValue As Variant, _
                     Optional ByVal FilterValue2 As Variant = Null, _
                     Optional ByVal IgnoreValue As Variant, _
                     Optional ByVal DisableIgnoreNullValue As Boolean = False) As String
...

Result as HTML (Is just a test, there are still many doxygen comments included that Natural Docs cannot format.):

• Homepage
• SqlTools CodeModule

The output is not as extensive as doxygen, but maybe I'm overlooking other possible optimizations.


Does anyone know of any other documentation tools that can generate documentation form source code?

 

[Uncle Gizmo]

I'd have a look at Chat GPT... I've seen it do some pretty clever things. You might be able to get it to edit your code in the way you desire. See this thread for more information:-

I'm in Love with ChatGPT

I'm writing a sci-fi story. Last week whilst on holiday I organised the chapters and included a brief summary of each chapter. After my recent success with chatGPT in finding "Fractoluminescence" I was itching to test its abilities once more! I copied my summary in to ChatGPT and asked chatGPT...

www.access-programmers.co.uk

 

[Josef P.]

Yes, you can do many things with ChatGPT.
I use it the other day to create regular expressions. That worked very well.

I don't think uploading multiple codemodules into ChatGPT and then having formatted code documentation created without any hints in the code will work.
Embedding the comments in ChatGPT will probably work.

My intention described in more detail:
I am not so much interested in including the comments in the code, but in creating a code documentation of the interfaces (e.g. as html structure) based on the methods and comments.
Note: I don't want to document the code itself. There I rather try to avoid comments in the code and shift the description to the naming of the procedures and variables.

However, an interface description also helps third parties who use the code modules but do not program in them themselves.
And for this I am looking for tools.

I currently know:

• Doxygen (I currently use)
• Natural Docs (after first tests I like it quite well)
• MZ-Tools (doesn't come close to the previous 2)

 

[Uncle Gizmo]

I wouldn't be quick to dismiss chat GPT.

If you watch this video a few times, I think you will get the idea.

The idea is to Iterate your questions. You ask Chat GTP a question, it doesn't return exactly what you want. You respond to it and hone your question until it returns what you want.

I suspect that if you follow the process as described in the above video, you will be surprised at the results.

 

[NauticalGent]

I use it the other day to create regular expressions.

hmmmm....

 

[Josef P.]

[OT]

I suspect that if you follow the process as described in the above video, you will be surprised at the results.

With ChatGPT I found Natural Docs via a few detours. The rest of the suggestions were non-existent tools.
(I do not have the Pro version.)
ChatGPT is quite useful. But in this case for the auto-automated interface description it does not help me.
I also use GitHub CoPilot myself - so don't worry, I definitely appreciate the capabilities of AI tools.

I'm not interested in writing the code comments with a tool, but in automated analysis of those comments to create automated documentation.
If I had to use ChatGPT for this, would I have to program with its API to get what?
I don't want to copy something by hand and copy back a result (html pages) later.
Creating an interface description is not a one-time process, but needs to be automated on an ongoing basis.

 

[Josef P.]

To close the thread, a quick info on Natural Docs, which I will be using from now on, as it is easy to read in code and provides sufficient html output for me.

Website: https://www.naturaldocs.org/
Source: https://github.com/NaturalDocs/NaturalDocs

VBA code is supported only by the comments. Procedures without comments are not listed.
With it however also the possibility exists to receive a hierarchy in the documentation, if one writes into the comment identifier of a class or a standard module thus a kind Namespace, as one knows it from C#.
Example:

' Class: data.odbc.OdbcHandler

This creates a tree: data -> odbc -> OdbcHandler

Compared to Doxygen, I currently lack a list of ToDo's or similar.
For this, writing the comment block is much more intuitive and the comment in the code is easier to read.

Example of created interface documentation: https://source.access-codelib.net/doc/ACLib-DbConnection-Framework/