Documentation tooling

[mansellan]

As we start to think about documentation, especially as it will be a community effort, one of the first questions to answer is: "What does the workflow for that look like?"

It would be hugely impractical to start writing raw HTML pages, we need a way of managing content. There's any number of ways of doing that, but which is best?

• Doxygen?
• DocFx?
• MdBook?
• Something else?

I would hope that source for documents could be stored in GitHub, along with some kind of spec for a table of contents and some kind of styling sheet. But what format should that be? Markdown? XML (please no...)? Something else?

[bclothier]

FWIW my votes goes to anything that uses markdown. As already mentioned elsewhere, I particularly like rust book format. Not sure what’s that based on. We should avoid technologies that ties you to one platform. I say that because today it might be more practical to use GH wiki, tomorrow, self hosted pages on twinbasic.com.

[KallunWillock]

Is this the one you're referring to? If so, it's uses mdBooks apparently which, as you might surmise from the name, comprises .md files.

[AlexHedley]

I'd vote for DocFX.

• Markdown
• json config
• Nice yaml toc (can have nested)
• theming
• matches MS

[sancarn]

I personally document all my code under a Doxygen / TSDoc syntax.

'Obtain a collection
'@param {vbVarType} Type of collection to create
'@returns {MyCollection<ofType>} The collection created under the specific type requirements
Function Create(ByVal ofType as vbVarType) as MyCollection
...

'Add an element of type `T` to a collection
'@param {ParamArray T|MyCollection<T>} The value (or values) to add to the collection
'@returns {MyCollection<T>} The new collection with the added value.
Function add(ParamArray v() as Variant) as MyCollection

The type override is extremely useful as it provides a flexible type system on an otherwise very static typing system. Of course if twinbasic gets an advanced typing system anyway perhaps this won't be required.

One thing to note is, Markdown isn't that great for detailing a sometimes infinite amount of detail.

A company I have worked with in the past hosts a number of different versions of a public API. For their specific case they have to seperate their API for different:

1. Piece of software
2. Workspace in software
3. Version IDs Min/Max

Below is a YAML doc containing most of what they'd like. It should be noted that it still has embedded markdown in some parts:

classes:
  - name: WSApplication
    description: The main API entry point.
    applications: [ICM, WSPRO, IA]
    methods:
      - name: add_ons_folder
        description: >-
          Obtain the file path of the 'add ons' folder.
          
          > Note - This folder will not exist unless manually created. It's parent folder will 
          exist if InfoWorks/IA has been opened on this PC.
        params: []
        returns: 
          type: string
          name: addonsPath
          description: Returns the full path of the 'add ons' folder e.g.
            `C:\Users\badgerb\AppData\Roaming\Innovyze\WorkgroupClient\scripts`
      - name: colour
        applications: [ICM, WSPRO, IA]
        workspaces: [UI]
        description: This method exists for convenience in the context of the `graph` method described below.
        Given 3 parameters, red, green and blue from 0 to 255 returns a colour with those red, green and blue values.
        params: 
          - name: red
          description: The red component of the color.
          type: number
          - name: green
          description: The green component of the color.
          type: number
          - name: blue
          description: The blue component of the color.
          type: number
        returns:
          name: color
          description: A color to use  in the `graph` method
          type: number
        examples:
          - applications: [ICM, WSPRO, IA]
            workspaces: [UI]
            description: Returns the color `black`.
            code: black=WSApplication.colour(0,0,0)
          - applications: [ICM, WSPRO, IA]
            workspaces: [UI]
            description: Returns the color `red`.
            code: black=WSApplication.colour(255,0,0)
          - applications: [ICM, WSPRO, IA]
            workspaces: [UI]
            description: Returns the color `white`.
            code: black=WSApplication.colour(255,255,255)

For such documentation a better approach would be using MDX:

<classes>
  <class name="WSApplication" applications=["ICM", "WSPRO", "IA"] workspaces: ["UI", "EXCHANGE"]>
    The main API entry point.
    
    <methods>
      <method name="add_ons_folder",
        Obtain the file path of the 'add ons' folder.
        
        > Note - This folder will not exist unless manually created. It's parent folder will 
        exist if InfoWorks/IA has been opened on this PC.
        
        </params>
        <returns name="addonsPath" type="string"> 
          Returns the full path of the 'add ons' folder e.g.
          `C:\Users\badgerb\AppData\Roaming\Innovyze\WorkgroupClient\scripts`
        </returns>
      </method>
      <method name="colour" applications=["ICM", "WSPRO", "IA"] workspaces: ["UI"]
        This method exists for convenience in the context of the `graph` method described below.
        Given 3 parameters, red, green and blue from 0 to 255 returns a colour with those red, green and blue values.

        <params>: 
          <param name="red" type="number">
            The red component of the color.
          </param>
          <param name="green" type="number">
            The green component of the color.
          </param>
          <param name="blue" type="number">
            The blue component of the color.
          </param>
        <params/>
        <returns name="color" type="number"> 
         A color to use  in the `graph` method
        </returns>
        <examples>
          <example applications=["ICM", "WSPRO", "IA"] workspaces=["UI"]>
            Returns the color `black`.
            
            ```rb
            black=WSApplication.colour(0,0,0)
            ```
          </example>
          <example applications=["ICM", "WSPRO", "IA"] workspaces=["UI"]>
            Returns the color `red`.
            
            ```rb
            red=WSApplication.colour(255,0,0)
            ```
          </example>
          <example applications=["ICM", "WSPRO", "IA"] workspaces=["UI"]>
            Returns the color `white`.
            
            ```rb
            white=WSApplication.colour(255,255,255)
            ```
          </example>
        </examples>
      </method>
    </methods>
  </class>
</classes>

But that does require knowledge of ReactJS, which admittedly is a shame.

[rexxitall]

This "´´´" as well the "Tag desert" does not look promising in my eyes. Oon such constructs it has to be considered that some characters are hard to type on some localized keyboards. I usually breaks my fingers to reach "[]{}" on a german keyboard. Markdown is in my opinion in any case the choice. Easy to learn and to write. If i would have to implement aomething like doxygen i would use something like '// as start and stop sequence (Easy to reach on any keyboard) . I also would use for all the lines in between the normal coment syntax at line start And for sure i would write something to fold it out of the way while coding. Everybody hates writing docs. So it should be made as easy and be fun as possible. Otherwise no one will use it ;) . But as sual - personal thoughts.

[wqweto]

Markdown is in my opinion in any case the choice. Easy to learn and to write.

Triple backticks (```{newline}...{newline}...{newline}```) is the markdown way to escape multi-line body of code while single backticks (`...`) are for inline code.

Formatting anything with markdown must be a hellish experience on your localized keyboard (my localized keyboard has no problems with these and square/curly brackets).

[FullValueRider]

We could be radical and use Open Office. Open office would just need an addin that scans a document for a 'code xxxxxx' field and provides that code to the language server when requested and then updates the code field with the output. Panes could be used to replicate all of the panels we are familiar with in our current ides. Furthermore the addin could abstract identifiers (as hyperlinks) from a code block (i.e. click in the code block and choose insert identifier) to facilitate referencing into code blocks. Naturally a document could host more than one code block. There would of course be options to export code as plain text with whatever portion of hyperlinked identifiers. Programmers would then be a free as they wish to include structured text for thier documentation, including graphics, animations, example spreadsheets etc etc etc.

[rexxitall]

An openOffice Addin would be a gift. Sure. But as long there is no VBx Interpreter in it it just makes half the sense. In my opinion one of the biggest mistakes they made and the reason why a lot of migration project fails. But OO as a documentation tool ? I am happy on my projects with a tool which makes pdf from MD and that can be started even by a cron job :) Keep simple things simple :) But this is just a personal meaning. The doc team will know best whats to use :)