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

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.

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

Replies are listed 'Best First'.
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]

Replies are listed 'Best First'.

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]