Re: (How) Do you document/test your private subroutines?

At work, we mostly use C and some C++. We use Doxygen to document it. All of the public stuff of a module is located in its header file, and so is the doxygen markdown for the public stuff. The private stuff and the implementation of public functions is in the C file, and we document it very much like the header file. That way, we can (hopefully) understand our code even in five years from now. Doxygen has the flags EXTRACT_ALL, EXTRACT_PRIVATE, and EXTRACT_STATIC that we set to YES to get the complete documentation. In some cases, the documentation of the public stuff is sufficient, so we can set those flags back to NO and get a much smaller documentation.

For helper code (perl, bash, Windows batch files), we do roughly the same, often by using doxygen with a custom input filter.

Code documentation is usally only a small part of our work. Medical and aerospace products require tons of paperwork, and the overhead grows with every new issue of the relevant standards. So documenting all of our code does not only help us maintain the code base, but also fulfils some obligatory requirements from the standards. And those of our clients that have bought the source code also get the complete documentation so they can modify the source on their own. Few clients actually do that, but they like the idea that they could.

In my perl code, I usually document everything, simply because I rarely need to touch my code. Documentation clearly helps to understand what I did years ago.

Alexander

--
Today I will gladly share my knowledge and experience, for there are no sweeter words than "I told you so". ;-)

Comment on Re: (How) Do you document/test your private subroutines?

Replies are listed 'Best First'.
Re^2: (How) Do you document/test your private subroutines? by stevieb (Canon) on Nov 07, 2018 at 00:12 UTC
Thanks afoken, at work (mostly C++ fronted by Python), we use a couple of techniques to do similar what you've stated here. I'm also in an industry that has extreme regulatory (ahem: paperwork) oversight, and even though clients have no idea what they're doing, they claim they want x, y and z regarding documentation, so we try to provide it. Some of this falls through the cracks though, due to everyone wanting to fit the next upgrade into the current budget cycle (I digress on all of that, this is more personal/Open Source). I've never used Doxygen before. Looks very interesting, and I will read up on it. At a cursory glance, it looks handy already for a few of my open projects. I like the diverse responses here so far.	[reply]
Re^3: (How) Do you document/test your private subroutines? by afoken (Chancellor) on Nov 08, 2018 at 21:08 UTC
I've never used Doxygen before. Looks very interesting, and I will read up on it. At a cursory glance, it looks handy already for a few of my open projects. A few more notes on doxygen: Doxygen comes with a very useful helper program called Doxywizard that allows to create a sane and well-documented Doxyfile with a few mouse clicks. Switching it to expert mode allows all kinds of fine-tuning. Plus, you can try all changes without actually changing the Doxyfile (Doxywizard feeds the configuration into doxygen from memory via STDIN). It is very recommended to install Graphviz. It creates useful (and very impressive) call graphs, class diagrams, and much more. All from normal code with doxygen comments, without any extra work (except for the computer). Our clients are regularily impressed by the amount of source code documentation that we generate. Most of that is automatically generated by doxygen and graphviz. We keep the Doxyfile in subversion and add a batch file or shell script named `build-docs` to automatically generate the documentation in HTML format in a directory docs just below the top-level directory of the project. Next to the script, we have a README.html that explains that doxygen needs to be installed, build-docs has to be started, and then links to where doxygen creates its output. The doxygen HTML output works much better with Javascript enabled. If you open the documentation from a filesystem (i.e. via a file:// URL), a modern browser will usually disable Javascript for security reasons. You may wish to add an exception or run a tiny webserver for viewing the documentation. Alexander -- Today I will gladly share my knowledge and experience, for there are no sweeter words than "I told you so". ;-)	[reply] [d/l]