Auto Produced Documentation 1

[XTnCIS]

Does anyone have guidance as to the value-of or the best software to use for producing automated software documentation.

 

[Frink]

Hallo,

What do you mean? It depends on who the documentation is for, users to use the application, or programmers (including yourself in 2 years time) to understand/modify the code.
Generally it's the why and how of software which is (more)important to know, rather than what each bit does.

Using a jukebox as an example...


For a User Guide, the first section should be a broad overview (2 pages max, ideally 1) to tell the reader what it does (or why you'd want to use it), the rational behind the user interface and what it can, and can't do. This should be easy to read, but not go into too many details.

Next you'll want a more detailed section on the use of the tool. Not what the tool does, and it's features, but more how the user uses the tool. This can be in the form of what a 'typical' user would need to do to start using the tool and should include lots of pictures:
Step-by-step installation (from the downloaded zip file to getting it up and running)
What the main set-up options are (indicating which CD drives you are to use, where you want to store your downloaded/ripped music data. What your preferred encoding method is etc. Don't include all the options, just the basic ones.
Then a section including how to rip a CD, how to store music downloaded from the web, how to play music from your library, how to burn a CD etc.
Another section can be used for more complex functions, such as editing music files or detailing how tracks are separated during playback (fade etc).
If you think the user needs more detailed help, then produce an Annex detailing each window, explaining each aspect of the window and what it's for and how to use it, step-by-step if necessary.
Another Annex can be used listing all the user options describing what each one does and why you would (or would not) want to change them.

The most important part of the user guide is the index. This should enable the user to look up loads of words and find where it is described in the document. It should also include synonyms such as write, copy or burn.

The way to check if your user guide is good enough is to give it to someone and watch them whilst they try and use your application. Write down everything they don't think is obvious or don't understand and re-write your User Guide, or your software.

For programmers:
You'll need to refer the reader to the user guide (in particular the first section) You wouldn't want them to even think about modifying the code without a clear understanding of how the tool is used.

You'll then only need a design document giving a high level design and indidicating the rational behind it. This you'll have to write from scratch (before you started coding?).

Once coding is completed update your design document to reflect any changes, then add a more detailed section.
This should be a more detailed summary of the features etc.
This should not be too detailed. ie. If you have a 'Import Track' button, just say something like "The Import Track button is used to move/copy a music file into your library directory structure. It uses the windows standard dialog box". Plus any other information which may be of help.
Do not describe the steps needed for a user to select a file (such as: select the drive the file is on using the Drive pull-down menu, then select the folder containing the required file etc.) If this level of detail needs to be provided (which it might) refer the user to the relevant section of the User Guide.
This way, if your dialog box changes, you won't need to change your design.
Any specific details which are not obvious, such as the types of file which can be loaded, and any conversion performed should also be included.

Include pictures wherever possible.

The code can be included in an annex, although I wouldn't as it becomes a nightmare to manage. If the programmer wants to see the code it would be easier in the module design view with its colour coding.

The code should be well commented, not on what each line of code does, but more what each section of code does and why it does it. Any complicated lines should be explained.
Variables should be renamed to accurately reflect their purpose, and type prefixes should be used.
What should be avoided in commenting is comments like

  I = I + 1  'Increment loop counter

Better to rename I as intFileLoop and remove the comment.
Some basic rules of good coding are use good variable/function names (explain what they're used for when you declare them) and if a comment just re-words the code then remove it.
Global variables need to have very good names and descriptions.
Each subroutine and function should have a brief description on what it does and what its entry and exit parameters are.

Finally, always use the same name for things, in the code and the hci and the documentation. This makes things a lot clearer.

Happy documenting,

- Frink

 

[XTnCIS]

Thank for all the information Frink! I appreciate you taking the time to give me your perspective.

My question centered on the programmer side of the documentation. I have the code documented (I did that while I was programming). And have found the documentation to be very useful even while I was finishing up the programming.

However, I am used to being able to see hard-copy of programming code and need to get an idea as to whether this is a hang-over from my programming training or a real need that I should meet for whoever (maybe myself) will be dealing with the software in the future.

I would love to have a tool that printed to code with loops identified (i.e. a line in the left margin)and maybe an index automatically created to all the procedures and functions.

Then again, there are all the individual properties that must be understood to really understand what is going on. It's not just in the 'code'.

I think you have given your view - that the future programmer should review the code from the screen.

What do other people have to say - and if anyone knows of an add-in that would do code printouts please let me know.

Thanks
XTnCIS

 

[Frink]

Hallo,

I see where you're coming from now.

I'd still rather look at code in an editor, in colour, and the loops should be obvious by the indentation.

Here's an idea, why not have a go at writing one yourself.
I expect it would be a challenge, but not impossible by any means.

- Frink

 

[rorubin]

Try this:

http://www.codeguru.com/vb/articles/2071.shtml

 

[Frink]

Hallo,

I thought I'd have a go at writing some sort of documentation tool as a bit of a programming exercise, so here it is. All it does is read in a text file containing a module, indents it according to the data in the table below. It indicates the blocks using the characters stored in chrBlockMarker.

If you fancy giving it a go then do the following:
Create a new database with a new table called tblKeywords as indicated below

strKeyword        intIndent  strEndKeyword  chrBlockMarker
(string*21)       (integer)  (string*21)    (string*1)
Case              2          Case           c
Do                2          Loop           l
DoCmd             0                           
DoEvents          0                          
Else              2          Else           e
For               2          Next           f
Function          2          End Function   F
If                2          End If         i
Private Function  2          End Function   F
Private Sub       2          End Sub        S
Private Type      2          End Type       t
Public Function   2          End Function   F
Public Sub        2          End Sub        S
Public Type       2          End Type       t
Select Case       4          End Select     s
Sub               2          End Sub        S
Type              2          End Type       t
While             2          Wend           h
With              2          End With       w

It also needs a module, with the following code in it:

Option Compare Database
Option Explicit

Private Const ysnUseLettersToIndicateBlocks As Boolean = True

Function ysnDocumentModule(ByVal txtInputFileName As String, ByVal txtOutputFileName As String) As Boolean
' print ysnDocumentModule("C:\Temp\InputFile.txt","C:\Temp\OutputFile.txt")
  Dim intInFileNo As Integer
  Dim intOutFileNo As Integer
  Dim strReadLine As String
  Dim intIndent As Integer
  Dim rstKeywords As Recordset
  Dim strDataLine As String
  Dim ysnNoEndMatch As Boolean
  Dim ysnNoMatch As Boolean
  Dim intSelectedIndent As Integer
  Dim intLongestKeyword As Integer
  Dim strIndent As String * 60
  
  ysnDocumentModule = True
  DoCmd.Hourglass True
  strIndent = Space$(60)
  intInFileNo = FreeFile
  Open txtInputFileName For Input As intInFileNo
  intOutFileNo = FreeFile
  Open txtOutputFileName For Output As intOutFileNo
  Set rstKeywords = CurrentDb.OpenRecordset("tblKeywords", dbOpenSnapshot, dbReadOnly)
  If rstKeywords.EOF Then Exit Function
  intIndent = 0
  Do While Not EOF(intInFileNo)
    Line Input #intInFileNo, strReadLine
    strReadLine = Trim$(strReadLine)
    strDataLine = strStripComment(strReadLine)
    strDataLine = strReplaceBadChars(Trim$(strDataLine))
    If strDataLine = "" Then
      Print #intOutFileNo, Left$(strIndent, intIndent) & strReadLine
    Else
      If Right$(strDataLine, 1) = ":" Then 'Label
        If intIndent > 2 Then
          intIndent = intIndent - 2
        Else
          intIndent = 0
        End If
        Print #intOutFileNo, strReadLine
        intIndent = intIndent + 2
      ElseIf strDataLine Like "If *" And strDataLine Like "* Then *" Then
        Print #intOutFileNo, Left$(strIndent, intIndent) & strReadLine
      Else
        intLongestKeyword = 0
        intSelectedIndent = 0
        rstKeywords.FindFirst "strEndKeyword = left$('" & strDataLine & "', Len(strEndKeyword))"
        ysnNoEndMatch = rstKeywords.NoMatch
        Do
          If Len(rstKeywords!strEndKeyword) > intLongestKeyword Then
            intLongestKeyword = Len(rstKeywords!strEndKeyword)
            intSelectedIndent = rstKeywords!intIndent
          End If
          rstKeywords.FindNext "strEndKeyword = left$('" & strDataLine & "', Len(strEndKeyword))"
        Loop Until rstKeywords.NoMatch
        If Not ysnNoEndMatch Then
          intIndent = intIndent - intSelectedIndent
        End If
        Print #intOutFileNo, Left$(strIndent, intIndent) & strReadLine
        intLongestKeyword = 0
        intSelectedIndent = 0
        rstKeywords.FindFirst "strKeyword = left$('" & strDataLine & "', Len(strKeyword))"
        ysnNoMatch = rstKeywords.NoMatch
        Do
          If Len(rstKeywords!strKeyword) > intLongestKeyword Then
            intLongestKeyword = Len(rstKeywords!strKeyword)
            intSelectedIndent = rstKeywords!intIndent
            If ysnUseLettersToIndicateBlocks Then
              Mid$(strIndent, intIndent + 1, 1) = rstKeywords!chrBlockMarker
            Else
              Mid$(strIndent, intIndent + 1, 1) = "¦"
            End If
          End If
          rstKeywords.FindNext "strKeyword = left$('" & strDataLine & "', Len(strKeyword))"
        Loop Until rstKeywords.NoMatch
        If Not ysnNoMatch Then intIndent = intIndent + intSelectedIndent
      End If
    End If
  Loop
  
lblExit:
  Close #intInFileNo
  Close #intOutFileNo
  DoCmd.Hourglass False
  Exit Function
lblErr:
  MsgBox Err.Description, vbExclamation, "Documenter"
  Resume lblExit
End Function

Function strStripComment(ByVal strLine As String) As String
  Dim intPtr As Integer
  Dim ysnInString As Boolean

  ysnInString = False
  intPtr = 1
  Do While intPtr <= Len(strLine)
    Select Case Mid$(strLine, intPtr, 1)
      Case &quot;&quot;&quot;&quot;
        ysnInString = Not ysnInString
      Case &quot;'&quot;
        If Not ysnInString Then Exit Do
    End Select
    intPtr = intPtr + 1
  Loop
  strStripComment = Left$(strLine, intPtr - 1)
End Function
Function strReplaceBadChars(ByVal strLine As String) As String
  Dim intPtr As Integer

  For intPtr = 1 To Len(strLine)
    If Mid$(strLine, intPtr, 1) = &quot;'&quot; Then Mid$(strLine, intPtr, 1) = &quot;q&quot;
    If Mid$(strLine, intPtr, 1) = &quot;&quot;&quot;&quot; Then Mid$(strLine, intPtr, 1) = &quot;Q&quot;
    If Mid$(strLine, intPtr, 1) = &quot;|&quot; Then Mid$(strLine, intPtr, 1) = &quot;¦&quot;
  Next intPtr
  strReplaceBadChars = strLine
End Function

That done, create a text file, C:\Temp\InputFile.txt and paste in a module of your own to document and save it.

Open the module, open the immediate window and enter

print ysnDocumentModule("C:\Temp\InputFile.txt","C:\Temp\OutputFile.txt")

After a short while it should say True. Then check C:\Temp\OutputFile.txt which should be your lovely module formatted. Hooray.

It may not for a number of reasons, usually due to keywords missing from tblKeywords.
Notice the DoCmd and DoEvents records. The code searches at the start of each line for the longest match in tblKeywords and uses the indIndent value for that record. If a match is found in strEndKeyword then the indent is reduced by intIndent. The line is output. If a match is found in strKeyword then the indent is increased by intIndent and the next line is processed.
Because it uses the longest match, DoCmd and DoEvents would be matched by Do and so indented which would be wrong, so they have to be explicitly given an entry with an indent of 0. There are probably more of these which I havent tested for. Another way of avoiding this problem would be to search for the keyword followed by a space, but that would need extra processing if the keyword was the only thing on the line.

Ideally it should produce RTF output, which could colour-code things, but there we go. I had to go to bed so couldn't do any more.

I was surprised about how short the code was. It doesn't handle comments on a line with nothing else very well (it aligns them with the code, which may not be what you want).
And it can get a bit confused with labels, but other than that it's not too bad.

If you prefer dotty lines rather than letters to identify blocks you can change ysnUseLettersToIndicateBlocks
I know it's not what you were looking for, but was fun to do,

- Frink

 

[XTnCIS]

Haum...

Thanks a lot Frink! I can't believe you spend the time to 'wip' this up like it was just something to do before you went to bed.

But to use your words - 'there we go'. I guess it's just something you do.

Thanks for your time and effort in helping me!
XTnCIS