Hacker Newsnew | past | comments | ask | show | jobs | submitlogin

> My pet peeve is auto-generated documentation from configuration files or source code. It is absolutely useless and I would rather prefer no documentation than auto-generated.

For most applications this approach is generally useless and should not be used. Comments should be in the code itself, and you expect people who want to work on the application to read at least some of the code. I.e. no reference / API documentation for applications, instead high level overview (where is what, application architecture etc.) and guides (how to set up your dev environment, how to contribute, how to prepare releases etc.).

For libraries it often makes sense to generate a reference documentation from the code itself. The drawback is that the strictly formulaic nature of comments parsed by the documentation generator has to be always kept in mind when writing the code itself. I.e. the comments need to make sense and be comprehensive when you remove them from the code surrounding them.

Some modules in the Python standard library are a good example of this. Quite a large amount of prose, separate from the code, and then a reference section generated from code. However, many modules have pretty bad documentation, where even the reference is missing crucial information (quite often very basic things like what a function returns).



> Comments should be in the code itself

Rust handles this nicely; its generated docs are based off source code comments. Same with Golang.




Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: