WTF is the point a
of auto-generated documentation. Some dude litterally thought it was a good idea to read the code and write the exact same shit differently. WTF IS THE POINT!?

Documentation takes work, sorry, stop being lazy.

It sure does~

I am using a tool that converts markdown to html for my documentation. Easy and quick to write plus deployment pipeline on update and I get nice structured website with search capabilities.

It’s better than nothing, which is usually what you get.

If you bother to write a description above functions and the generator fetches that, then I’d argue it’s ok

The original idea of "autogenerated" (to be read as "extracted" or "autoassembled") documentation is that you can write documentation while you write the parts of the software and that you don't have to write the documentation boilerplates. In addition to the more or less (depends on type system) automatically derived type information, information from comments is added to the assembled documentation.

The coder still has to write the actual documentation of purpose/use/quirks/examples for parts at various scope levels (package, module, class, struct, method/function) into special comments to actually get documentation instead of just a (more or less complete depending on language) type tree as result.

For low-level documentation, a documentation extractor can be very helpful. It also ticks the checkbox on some requirement lists...

@Earu thats exactly how most documentation is generated.

Annotate the function with a special Block that the docs generator reads and generate content from.

@PappyHans I use that too actually, I love it. Though you still wrote your documentation at the end of the day, so not the same issue ;-)

@Ikaroz interesting, I personally just write a readme.md file in each component folder. Not only does it insured proper separation of concerns/file structure, but it also ensures that everything gets documented.

It's a convenient tool, when you don't care about implementation. As a writer of any implementation, you need to keep the original docs embedded in same context. The quality of auto-generation will be proportional to what developers documented in original file.

I like it, we use doxygen in one of our products and I really prefer it to manually writing/updating docs.

First of all you don’t even need to open generated docs, since all information about files/functions/variables are already on the source code as comments.

Also when you make a change, you see the comment right above telling lies it hurts your soul not to update it. Knowing docs are generated from it, you end up updating the comment hence docs then and there. Plus if you add or remove a parameter from a function doxygen displays error messages regarding the parameter that doesn’t have its comment above its function declaration.

It's nice for django rest framework where an API documentation more or less falls out of the code, you just need to provide help messages on the django model

Well, in reality it's a bit more complex than that, using a 3rd party tool for better docs and having to manually annotate a bit of stuff if you hack Django to do weird stuff, but definitely better than an undocumented API or a documentation that gets outdated around the second it's finished