Writing documentation of your modules/barrels and what not

Hello,

how do people write documentation for MonkeyC code? I have a couple of modules/classes/etc that I want to add some documenation around so I can look it up without having to read the code. What kind of tools do you guys use for this? I want to have my documentation also available in markdown if that is possible.

Top Replies

waterkip over 2 years ago +1 verified

I'd like to answer my own post. I am using NaturalDocs (an older version of it anyways) to generate documentation. I have a CI pipeline that generates the docs and puts it on Gitlab pages.

You write…

All Replies

0 jim_m_58 over 2 years ago

I just do stuff like this as comments in the code. Some at the beginning of the file, so I can just look at that. Some if I'm doing something tricky within the code, etc.

0 FlowState over 2 years ago in reply to jim_m_58

waterkip said:
without having to read the code

jim_m_58 said:
I just do stuff like this as comments in the code

0 jim_m_58 over 2 years ago in reply to FlowState

A Section at the beginning of the code. Some do that with the license agreement for example. That way the documentation isn't separate from the code.

0 FlowState over 2 years ago in reply to jim_m_58

jim_m_58 said:
A Section at the beginning of the code. Some do that with the license agreement for example. That way the documentation isn't separate from the code.

You realize there are tools that allow you to write documentation as comments within code, and also extract said documentation to separate files, as well as allowing the documentation to be displayed in other contexts (like when you hover over a symbol)? Sort of a best of both worlds situation. You can view the docs inline within in the code, by hovering over a symbol or by looking at generated doc files (sans code).

Javadoc is decades old and Garmin obviously has its own tool that they use for HTML docs in their sample apps, but they didn't feel like sharing it with us (or telling us which standard tool they used, if any), nor did they bother to implement support in the Monkey C VS Code plugin to display said documentation when you hover over a symbol.

But thanks for your insight about how to write documentation that can be accessed without looking at the code...by putting comments in the code.

Just another variant of the standard response where you imply (or outright state) that what the OP is asking for isn't important because you don't use it or need it, with the added twist of providing an answer that is completely obvious to everyone and was explicitly not asked for. You should probably be able to tell from the OP's question (and their previous posts) that they're not a day 1 programmer who doesn't know what "comments" are.

I repeat, Garmin generates HTML docs from Monkey C source for its sample apps, so at least Garmin thinks it's important.

0 jim_m_58 over 2 years ago in reply to FlowState

You do love to whine!

0 FlowState over 2 years ago in reply to jim_m_58

Same as you love to provide useless/condescending/incorrect answers to any question that's outside your area of interest/expertise or requires any additional thought or discussion at all.

"I want to write docs that I can refer to without looking at code. Any suggestions?"

"Have you considered putting comments in your code?"

(Also, others have wondered why Garmin doesn't release their own doc solution to Monkey C devs.)

+1 waterkip over 2 years ago

I'd like to answer my own post. I am using NaturalDocs (an older version of it anyways) to generate documentation. I have a CI pipeline that generates the docs and puts it on Gitlab pages.

You write your documention like so:

      /*
        Function: getBoxCoords(args)

        Parameters:
          * :size, required
          * :canvas, optional
          * :degrees, optional
          * :hours, optional
          * :minutes, optional
          * :radians, optional

        You need to supply at least one of :degrees, :hours, :minutes, :radians
      */

Which than looks something like this on the generated HTML page: waterkip.gitlab.io/.../Coordinates-mc.html

0 FlowState over 2 years ago in reply to waterkip

But have you considered putting comments in your code??? A Section at the beginning of the code. That way the documentation. Isn't separate from the code.

Jk, thanks for sharing! I do wish Garmin would share their own docgen solution and incorporate it into the Monkey C plugin (e.g. show doc on hover), but I guess that makes me a whiner.

0 dpawlyk over 2 years ago in reply to FlowState

FlowState said:
"I want to write docs that I can refer to without looking at code. Any suggestions?"

"Have you considered putting comments in your code?"

It's entirely valid to suggest that what the OP wants to do should be reconsidered.

Your suggestion to use something that lets you extract comments in the code is a good one.