Writing documentation of your modules/barrels and what not

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.

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.

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.

You do love to whine!  

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.)

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.

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.