
Ask HN: How does code documentation work in your company? - billconan
Do you generate code documentation at work?<p>Do you use sphinx or doxygen? (other alternatives?) or you use a separate wiki? How does code documentation kept in sync with the code?<p>Any other methods? What are the problems (with doxygen for example?).<p>Does your company have a good culture to encourage code documentation?
======
vedranm
I work in an academic setting and have contributed to a number of open source
projects (GROMACS [1], LLVM [2], ns-3 [3], CP2K [4]), so I might not fit in
the sample you are trying to ask. Regardless, here are the answers:

> Do you generate code documentation at work?

Yes.

> Do you use sphinx or doxygen? (other alternatives?) or you use a separate
> wiki?

All three. :-) Sphinx is used for the tutorial-like documentation (including
lectures intended for students [5], seems to be a quite common practice in the
recent years [6]), but not for the API documentation; Doxygen is used for the
API documentation. Sole exception to this combination is CP2K (which uses
custom solutions for both).

Wiki is used like an internal notebook, and sometimes we clean up our notes
and publish them for everyone to see (e.g. from my former lab [7]). The
documentation migration effort in GROMACS [8] is another example of clean up
and publish, where the content accumulated over the years in the wiki is being
cleaned up and included in the documentation processed by Sphinx.

> How does code documentation kept in sync with the code?

With Doxygen you can't avoid not keeping it up to date since it prints the
warnings while producing the documentation. With Sphinx, it's manual and far
more tedious, but usually code reviews catch "you didn't document your new
feature and/or UX change" situations. With wikis (at least in our case) it's
even worse, since it's far away from the code and mostly just written down
notes.

> Any other methods? What are the problems (with doxygen for example?)

Regarding Doxygen, CP2K maintainers decided against using it because the
resulting look of the documentation for Fortran was sub-optimal. For C/C++,
the project maintainers/contributors (including myself) are quite happy with
the result. Haven't used it for other languages so far.

> Does your company have a good culture to encourage code documentation?

I would say yes, it's encouraged through code reviews on the projects.

Hope this helps.

[1] [http://www.gromacs.org/](http://www.gromacs.org/)

[2] [https://llvm.org/](https://llvm.org/)

[3] [https://www.nsnam.org/](https://www.nsnam.org/)

[4] [https://www.cp2k.org/](https://www.cp2k.org/)

[5]
[https://lab.miletic.net/en/teaching/](https://lab.miletic.net/en/teaching/)

[6]
[https://becksteinlab.physics.asu.edu/pages/courses/2013/SimB...](https://becksteinlab.physics.asu.edu/pages/courses/2013/SimBioNano/)

[7]
[https://www.svedruziclab.com/wiki/Software](https://www.svedruziclab.com/wiki/Software)

[8]
[https://redmine.gromacs.org/projects/gromacs/wiki/Documentat...](https://redmine.gromacs.org/projects/gromacs/wiki/Documentation_migration)

