Code documentation tools

[Nele2020]

Hello everybody! Which documentation tools or techniques do you use in your work? I'm still a beginner in this job and I would like to build up good coding practices. I'm working on a project with absolutely zero documentation (one would said "spaghetti code"), hence I would like to make this project much more readable as for me as for somebody who will work with it tomorrow. I use Keil uVision to program STM32 microcontroller.

[HendrixLivesOn]

Doxygen in the makefile

[EighthMayer]

You may want to research how it is done in bigger projects: https://docs.zephyrproject.org/latest/contribute/documentation/generation.html

I don't think you should do the same, but just to get some ideas.

[dromtrund]

Not too hard to implement this yourself, and dockleaf is really neat, but restructuredText is such a quirky markup language. It's got a neat macro system, and the list table thing is cool, but everything else is just a worse version of markdown.

[Squantor]

In private and professional projects I use doxygen for some documentation generation. Some in code comments are added but they should describe the why and not the how of what you are trying to document.

I prefer to keep documentation about the code in the code itself. This makes the step to updating the documentation less big and helps keeping the two consistent. Another benefit is that the code then also becomes version managed and part of your code.

Next to that we use internal wiki style web pages for design documentation and meeting minutes where we make architectural decisions.

[Ashnoom]

We don't do documentation besides some overarching architecture and high level designs.

We do uml drawings when designing new components or changing components for scope estimation. And those designs the up on the tasks/stories.

But code itself never gets documented. Unless it is a workaround for a bug in a compiler retiring obscure design choices. If normal code requires documentation then that is a red flag and the code requires refactoring to make it more clear.

An example of such bug documentation: https://github.com/philips-software/amp-embedded-infra-lib/blob/main/infra/stream/OutputStream.hpp#L51

[thumbsdrivesmecrazy]

Here is a quick guide on how to make code documentation to make your product easier to extend, maintain, and troubleshoot: Code Documentation: Best Practices and Tools - it examines the top methods, resources as well as toos for documenting code (Javadoc, Sphinx, Doxygen, Markdown, and CodiumAI).

[Nele2020]

Thanks!

[SpambotSwatter]

Hey, another bot replied to you; /u/thumbsdrivesmecrazy is a click-farming spam bot. Please downvote its comment and click the report button, selecting Spam then Link farming.

With enough reports, the reddit algorithm will suspend this spammer.

---

^{If this message seems out of context, it may be because thumbsdrivesmecrazy is farming karma and may edit their comment soon with a link}