Just how does one document software?
I'm a complete autodidact when it comes to software, but I've been writing microcontroller software for most of my career, and no-one has ever has asked me to document it. Now, I'm thinking of retiring within the next few years and whilst I could behave like a complete bastard and just leave my successor to sort out the mess, I'm not that sort of bloke; and perhaps it really should be properly documented now.
Whilst I might like to think that I write perfectly lucid code that is perfectly obvious to anyone reading it what it does, that might just be a matter of opinion; so, are there standardised ways of documenting C, beyond writing the odd comment line? To what level of granularity should it be explained?
And how? In natural language or by flowchart?

 

It is too late now and that's just my opinion. I strongly believe in the strategy of "Write the user manual first!".

If the code was written properly in the first place, it should be self documenting. You should never have to comment a line of code. At the very least, every subfunction and subroutine should have a header section. This would describe the purpose of the function, input and output parameters, any global variables referenced, any system resources, and other global dependencies.

The main program itself should have a header section containing programmer names, date, revision dates, and actual revisions made. When I say header sections, I mean plain text documentation.

Large projects would be organized in separate source files and header files. This is where it gets complicated. No one knows what are in the header file until you actually open it and read it. Take a look at some commercial IDE implementation of large libraries and see how they document the header files and source files.

 

Go back 5 or 10 years ago and look at some of your code for that period. If it's clear and obvious what every function does, if it's clear why each datum exists and where it's used, then code documentation will be easy. Hire or get a underling to learn Doxygen.

https://www.doxygen.nl/

 

Go back 5 or 10 years ago and look at some of your code for that period. If it's clear and obvious what every function does, if it's clear why each datum exists and where it's used, then code documentation will be easy. Hire or get a underling to learn Doxygen.

https://www.doxygen.nl/

Thanks.
I had to check 5 year old code the other day, and it was immediately obvious what it did, and I fixed the bug in 10 minutes.
The only thing not done well was the weird-and-wonderful constant which the squarerooted averaged squared raw ADC value was multiplied by to get the RMS voltage. Next time I'll #define RMSVOLTAGEFACTOR.

I looked at Doxygen. Should I trust documentation software which has documentation which is not easy to follow?
For instance, it tells me to type:
cd doxygen-$VERSION (and I do know that that means I actually type 1.13.2 instead of $VERSION
mkdir build
cd build
So now I am in an empty directory, so when I type
cmake -G "Unix Makefiles" . .
it says that there are no files to build and complains about the two trailing dots.
Most Linux software these days seems to be supplied with a file which can be run after changing the permissions.

 

A few decades ago I asked a programming architect to supply documentation for a program his group was working for my group. His answer was “The code is self-documenting.” and sure enough it was. That would have been more useful if I understood C.

Just keep in mind who might need to read your richly commented code.

 

A few years ago I was talking to a former student that had gone to work for a pretty well-respected software company and was surprised that their general policy was that code should have virtually no comments (beyond a standard header block at the top of each file). At first I thought he was pulling my leg, but after he explained their rationale, it made sense. That's not to say that I completely agreed with it, but I could definitely see the value in trying to push developers in that direction. The first thing he pointed out was that code comments have a tendency to get out of date, which makes them worse than useless. Someone writes some very well thought out comments for a function or a block of code and then the code changes, often by the same person that wrote the beautiful comments. It gets tweaked, or fixed, or improved, but the comments don't get updated, or not updated carefully. I know that I have been guilty of that offense more than once. So now there is a mismatch between the two which can confuse or mislead people that read it later. But if there are no comments, then there is no mismatch. Which brings up the second point, which is that if comments are not going to used, the code needs to be self-documenting. This is, of course, easier said than done, but if that's the policy and the culture, then developers learn how to write self-documenting code.

As I pressed him on things, it became clear that the software they generally develop is not performance bound, so they can accept a pretty severe performance penalty in exchange for writing code that is organized and written so that it matches the high-level human-oriented structure of the software.

As I thought about this some more, I realized that I typically write code along these same lines, trying to make the code as self-documenting as I can, including accepting performance hits that are tolerable instead of throwing tricks and optimizations that, yes, make the code perform better, but at the expense of making it very obscure and in need of lots of comments. I used to love spending the time and effort to squeeze performance out of code -- hey, most real engineers do, right? -- but that was before I fully grasped the notion that if the solution is good enough, then it's good enough. Code that performs acceptably well and is easy to understand and maintain is far, far more valuable than code that performs better than there is any need for and is cryptic and difficult to maintain.

But I also firmly believe that engineers should never say never or insist on hard dogmatic rules. Sometimes ya gotta do whatcha gotta do. So if you need to play cryptic games to get acceptable performance, do it. But comment the daylights out of that block of code.

This approach applies not just to code, but schematics or anything else where there is a similar kind of understandability versus performance tradeoff.

 

Thanks.
I had to check 5 year old code the other day, and it was immediately obvious what it did, and I fixed the bug in 10 minutes.
The only thing not done well was the weird-and-wonderful constant which the squarerooted averaged squared raw ADC value was multiplied by to get the RMS voltage. Next time I'll #define RMSVOLTAGEFACTOR.

I looked at Doxygen. Should I trust documentation software which has documentation which is not easy to follow?
For instance, it tells me to type:
cd doxygen-$VERSION (and I do know that that means I actually type 1.13.2 instead of $VERSION
mkdir build
cd buildt
So now I am in an empty directory, so when I type
cmake -G "Unix Makefiles" . .
it says that there are no files to build and complains about the two trailing dots.
Most Linux software these days seems to be supplied with a file which can be run after changing the permissions.

If you can write decent software you can understand how doxygen works.

I did say have another do the setup for you.
https://jasoncc.github.io/doc_tools/doxygen.html

 

Simple doxygen generated documentation example with no additional changes to C source code.
Install the software.
https://jasoncc.github.io/doc_tools/doxygen.html
https://www.doxygen.nl/download.html

doxygen -g ha.doxygen
Edit the ha.doxygen config file.
https://github.com/nsaspook/ha_energy/blob/fsm_main/bmc/ha.doxygen

Also changed this line in addition to the lines listed in the first doc_tools link to setting up a config file.
OPTIMIZE_OUTPUT_FOR_C = YES
doxygen ha.doxygen

cd to the created html directory

firefox index.html

HA Energy: energy.c
https://github.com/nsaspook/ha_energy/tree/fsm_main/bmc/html

 

MPLABX has a doxygen integration plugin.
Windows example for some PIC18F47Q84 C code using XC8.

                ADC_DischargeSampleCapacitor();
                ADC_StartConversion(channel_ANA1);
                while (!ADC_IsConversionDone()) {
                };
                if (ADC_IsConversionDone()) {
                    V.v_tx_line = ADC_GetConversionResult();
                };
                ADC_DischargeSampleCapacitor();
                ADC_StartConversion(channel_ANA2);
                while (!ADC_IsConversionDone()) {
                };
                if (ADC_IsConversionDone()) {
                    V.v_rx_line = ADC_GetConversionResult();
                };
                // convert ADC values to char for display
                update_rs232_line_status();

secs_q84/Doxyfile for doxygen documentation generation.

# Doxyfile 1.8.13

#---------------------------------------------------------------------------
# Project related configuration options
#---------------------------------------------------------------------------
DOXYFILE_ENCODING = UTF-8
PROJECT_NAME = secs_q84
PROJECT_NUMBER =
PROJECT_BRIEF =
PROJECT_LOGO =
OUTPUT_DIRECTORY = C:\Users\nsasp\AppData\Roaming\DoxygenOutput
CREATE_SUBDIRS = NO
ALLOW_UNICODE_NAMES = NO
OUTPUT_LANGUAGE = English
BRIEF_MEMBER_DESC = YES
REPEAT_BRIEF = YES
ABBREVIATE_BRIEF = "The $name class" \
"The $name widget" \
"The $name file" \
is \
provides \
specifies \
contains \
represents \
a \
an \
the
ALWAYS_DETAILED_SEC = NO
INLINE_INHERITED_MEMB = NO
FULL_PATH_NAMES = YES
STRIP_FROM_PATH =
STRIP_FROM_INC_PATH =
SHORT_NAMES = NO
JAVADOC_AUTOBRIEF = NO
QT_AUTOBRIEF = NO
MULTILINE_CPP_IS_BRIEF = NO
INHERIT_DOCS = YES
SEPARATE_MEMBER_PAGES = NO
TAB_SIZE = 4
ALIASES =
TCL_SUBST =
OPTIMIZE_OUTPUT_FOR_C = YES
OPTIMIZE_OUTPUT_JAVA = NO
OPTIMIZE_FOR_FORTRAN = NO
OPTIMIZE_OUTPUT_VHDL = NO
EXTENSION_MAPPING =
MARKDOWN_SUPPORT = YES
TOC_INCLUDE_HEADINGS = 0
AUTOLINK_SUPPORT = YES
BUILTIN_STL_SUPPORT = NO
CPP_CLI_SUPPORT = NO
SIP_SUPPORT = NO
IDL_PROPERTY_SUPPORT = YES
DISTRIBUTE_GROUP_DOC = NO
GROUP_NESTED_COMPOUNDS = NO
SUBGROUPING = YES
INLINE_GROUPED_CLASSES = NO
INLINE_SIMPLE_STRUCTS = NO
TYPEDEF_HIDES_STRUCT = NO
LOOKUP_CACHE_SIZE = 0
#---------------------------------------------------------------------------
# Build related configuration options
#---------------------------------------------------------------------------
EXTRACT_ALL = YES
EXTRACT_PRIVATE = NO
EXTRACT_PACKAGE = NO
EXTRACT_STATIC = NO
EXTRACT_LOCAL_CLASSES = YES
EXTRACT_LOCAL_METHODS = NO
EXTRACT_ANON_NSPACES = NO
HIDE_UNDOC_MEMBERS = NO
HIDE_UNDOC_CLASSES = NO
HIDE_FRIEND_COMPOUNDS = NO
HIDE_IN_BODY_DOCS = NO
INTERNAL_DOCS = NO
CASE_SENSE_NAMES = NO
HIDE_SCOPE_NAMES = YES
HIDE_COMPOUND_REFERENCE= NO
SHOW_INCLUDE_FILES = YES
SHOW_GROUPED_MEMB_INC = NO
FORCE_LOCAL_INCLUDES = NO
INLINE_INFO = YES
SORT_MEMBER_DOCS = YES
SORT_BRIEF_DOCS = NO
SORT_MEMBERS_CTORS_1ST = NO
SORT_GROUP_NAMES = NO
SORT_BY_SCOPE_NAME = NO
STRICT_PROTO_MATCHING = NO
GENERATE_TODOLIST = YES
GENERATE_TESTLIST = YES
GENERATE_BUGLIST = YES
GENERATE_DEPRECATEDLIST= YES
ENABLED_SECTIONS =
MAX_INITIALIZER_LINES = 30
SHOW_USED_FILES = YES
SHOW_FILES = YES
SHOW_NAMESPACES = YES
FILE_VERSION_FILTER =
LAYOUT_FILE =
CITE_BIB_FILES =
#---------------------------------------------------------------------------
# Configuration options related to warning and progress messages
#---------------------------------------------------------------------------
QUIET = NO
WARNINGS = YES
WARN_IF_UNDOCUMENTED = YES
WARN_IF_DOC_ERROR = YES
WARN_NO_PARAMDOC = NO
WARN_AS_ERROR = NO
WARN_FORMAT = "$file:$line: $text"
WARN_LOGFILE =
#---------------------------------------------------------------------------
# Configuration options related to the input files
#---------------------------------------------------------------------------
INPUT = C:/Users/nsasp/vtouch_v2/secs_q84.X
INPUT_ENCODING = UTF-8
FILE_PATTERNS = *.c \
*.cc \
*.cxx \
*.cpp \
*.c++ \
*.java \
*.ii \
*.ixx \
*.ipp \
*.i++ \
*.inl \
*.idl \
*.ddl \
*.odl \
*.h \
*.hh \
*.hxx \
*.hpp \
*.h++ \
*.cs \
*.d \
*.php \
*.php4 \
*.php5 \
*.phtml \
*.inc \
*.m \
*.markdown \
*.md \
*.mm \
*.dox \
*.py \
*.pyw \
*.f90 \
*.f95 \
*.f03 \
*.f08 \
*.f \
*.for \
*.tcl \
*.vhd \
*.vhdl \
*.ucf \
*.qsf
RECURSIVE = YES
EXCLUDE =
EXCLUDE_SYMLINKS = NO
EXCLUDE_PATTERNS =
EXCLUDE_SYMBOLS =
EXAMPLE_PATH =
EXAMPLE_PATTERNS = *
EXAMPLE_RECURSIVE = NO
IMAGE_PATH =
INPUT_FILTER =
FILTER_PATTERNS =
FILTER_SOURCE_FILES = NO
FILTER_SOURCE_PATTERNS =
USE_MDFILE_AS_MAINPAGE =
#---------------------------------------------------------------------------
# Configuration options related to source browsing
#---------------------------------------------------------------------------
SOURCE_BROWSER = YES
INLINE_SOURCES = NO
STRIP_CODE_COMMENTS = YES
REFERENCED_BY_RELATION = NO
REFERENCES_RELATION = NO
REFERENCES_LINK_SOURCE = YES
SOURCE_TOOLTIPS = YES
USE_HTAGS = NO
VERBATIM_HEADERS = YES
CLANG_ASSISTED_PARSING = NO
CLANG_OPTIONS =
#---------------------------------------------------------------------------
# Configuration options related to the alphabetical class index
#---------------------------------------------------------------------------
ALPHABETICAL_INDEX = YES
COLS_IN_ALPHA_INDEX = 5
IGNORE_PREFIX =
#---------------------------------------------------------------------------
# Configuration options related to the HTML output
#---------------------------------------------------------------------------
GENERATE_HTML = YES
HTML_OUTPUT = html
HTML_FILE_EXTENSION = .html
HTML_HEADER =
HTML_FOOTER =
HTML_STYLESHEET =
HTML_EXTRA_STYLESHEET =
HTML_EXTRA_FILES =
HTML_COLORSTYLE_HUE = 220
HTML_COLORSTYLE_SAT = 100
HTML_COLORSTYLE_GAMMA = 80
HTML_TIMESTAMP = NO
HTML_DYNAMIC_SECTIONS = NO
HTML_INDEX_NUM_ENTRIES = 100
GENERATE_DOCSET = NO
DOCSET_FEEDNAME = "Doxygen generated docs"
DOCSET_BUNDLE_ID = org.doxygen.Project
DOCSET_PUBLISHER_ID = org.doxygen.Publisher
DOCSET_PUBLISHER_NAME = Publisher
GENERATE_HTMLHELP = NO
CHM_FILE =
HHC_LOCATION =
GENERATE_CHI = NO
CHM_INDEX_ENCODING =
BINARY_TOC = NO
TOC_EXPAND = NO
GENERATE_QHP = NO
QCH_FILE =
QHP_NAMESPACE = org.doxygen.Project
QHP_VIRTUAL_FOLDER = doc
QHP_CUST_FILTER_NAME =
QHP_CUST_FILTER_ATTRS =
QHP_SECT_FILTER_ATTRS =
QHG_LOCATION =
GENERATE_ECLIPSEHELP = NO
ECLIPSE_DOC_ID = org.doxygen.Project
DISABLE_INDEX = NO
GENERATE_TREEVIEW = NO
ENUM_VALUES_PER_LINE = 4
TREEVIEW_WIDTH = 250
EXT_LINKS_IN_WINDOW = NO
FORMULA_FONTSIZE = 10
FORMULA_TRANSPARENT = YES
USE_MATHJAX = NO
MATHJAX_FORMAT = HTML-CSS
MATHJAX_RELPATH = http://cdn.mathjax.org/mathjax/latest
MATHJAX_EXTENSIONS =
MATHJAX_CODEFILE =
SEARCHENGINE = YES
SERVER_BASED_SEARCH = NO
EXTERNAL_SEARCH = NO
SEARCHENGINE_URL =
SEARCHDATA_FILE = searchdata.xml
EXTERNAL_SEARCH_ID =
EXTRA_SEARCH_MAPPINGS =
#---------------------------------------------------------------------------
# Configuration options related to the LaTeX output
#---------------------------------------------------------------------------
GENERATE_LATEX = YES
LATEX_OUTPUT = latex
LATEX_CMD_NAME = latex
MAKEINDEX_CMD_NAME = makeindex
COMPACT_LATEX = NO
PAPER_TYPE = a4
EXTRA_PACKAGES =
LATEX_HEADER =
LATEX_FOOTER =
LATEX_EXTRA_STYLESHEET =
LATEX_EXTRA_FILES =
PDF_HYPERLINKS = YES
USE_PDFLATEX = YES
LATEX_BATCHMODE = NO
LATEX_HIDE_INDICES = NO
LATEX_SOURCE_CODE = NO
LATEX_BIB_STYLE = plain
LATEX_TIMESTAMP = NO
#---------------------------------------------------------------------------
# Configuration options related to the RTF output
#---------------------------------------------------------------------------
GENERATE_RTF = NO
RTF_OUTPUT = rtf
COMPACT_RTF = NO
RTF_HYPERLINKS = NO
RTF_STYLESHEET_FILE =
RTF_EXTENSIONS_FILE =
RTF_SOURCE_CODE = NO
#---------------------------------------------------------------------------
# Configuration options related to the man page output
#---------------------------------------------------------------------------
GENERATE_MAN = NO
MAN_OUTPUT = man
MAN_EXTENSION = .3
MAN_SUBDIR =
MAN_LINKS = NO
#---------------------------------------------------------------------------
# Configuration options related to the XML output
#---------------------------------------------------------------------------
GENERATE_XML = NO
XML_OUTPUT = xml
XML_PROGRAMLISTING = YES
#---------------------------------------------------------------------------
# Configuration options related to the DOCBOOK output
#---------------------------------------------------------------------------
GENERATE_DOCBOOK = NO
DOCBOOK_OUTPUT = docbook
DOCBOOK_PROGRAMLISTING = NO
#---------------------------------------------------------------------------
# Configuration options for the AutoGen Definitions output
#---------------------------------------------------------------------------
GENERATE_AUTOGEN_DEF = NO
#---------------------------------------------------------------------------
# Configuration options related to the Perl module output
#---------------------------------------------------------------------------
GENERATE_PERLMOD = NO
PERLMOD_LATEX = NO
PERLMOD_PRETTY = YES
PERLMOD_MAKEVAR_PREFIX =
#---------------------------------------------------------------------------
# Configuration options related to the preprocessor
#---------------------------------------------------------------------------
ENABLE_PREPROCESSING = YES
MACRO_EXPANSION = NO
EXPAND_ONLY_PREDEF = NO
SEARCH_INCLUDES = YES
INCLUDE_PATH =
INCLUDE_FILE_PATTERNS =
PREDEFINED =
EXPAND_AS_DEFINED =
SKIP_FUNCTION_MACROS = YES
#---------------------------------------------------------------------------
# Configuration options related to external references
#---------------------------------------------------------------------------
TAGFILES =
GENERATE_TAGFILE =
ALLEXTERNALS = NO
EXTERNAL_GROUPS = YES
EXTERNAL_PAGES = YES
PERL_PATH = /usr/bin/perl
#---------------------------------------------------------------------------
# Configuration options related to the dot tool
#---------------------------------------------------------------------------
CLASS_DIAGRAMS = YES
MSCGEN_PATH =
DIA_PATH =
HIDE_UNDOC_RELATIONS = YES
HAVE_DOT = NO
DOT_NUM_THREADS = 0
DOT_FONTNAME = Helvetica
DOT_FONTSIZE = 10
DOT_FONTPATH =
CLASS_GRAPH = YES
COLLABORATION_GRAPH = YES
GROUP_GRAPHS = YES
UML_LOOK = NO
UML_LIMIT_NUM_FIELDS = 10
TEMPLATE_RELATIONS = NO
INCLUDE_GRAPH = YES
INCLUDED_BY_GRAPH = YES
CALL_GRAPH = NO
CALLER_GRAPH = NO
GRAPHICAL_HIERARCHY = YES
DIRECTORY_GRAPH = YES
DOT_IMAGE_FORMAT = png
INTERACTIVE_SVG = NO
DOT_PATH =
DOTFILE_DIRS =
MSCFILE_DIRS =
DIAFILE_DIRS =
PLANTUML_JAR_PATH =
PLANTUML_CFG_FILE =
PLANTUML_INCLUDE_PATH =
DOT_GRAPH_MAX_NODES = 50
MAX_DOT_GRAPH_DEPTH = 0
DOT_TRANSPARENT = NO
DOT_MULTI_TARGETS = NO
GENERATE_LEGEND = YES
DOT_CLEANUP = YES

 

As you can see, it's not that hard to get doxygen going on Linux or Windows for C. It's a very easy way to create detailed software docs from nothing but source code. There are specific doxygen prefixes and headers that can be used in comments for extra documentation of source files designed to use doxygen as they are created.

https://www.doxygen.nl/manual/docblocks.html


Javadoc style doxygen comments


Text for the main in the generated html files.

 

You mentioned "MPLAB Plugin" which made me wonder if there might be an E2Studio plug-in because I think they are both running on Eclipse, and indeed there is.
So I installed it, and now I have rather a better idea of what it does:
It takes the comment lines out of your program and presents them in a format and filetype that can be understood by managers with a little technical ability.

 

You mentioned "MPLAB Plugin" which made me wonder if there might be an E2Studio plug-in because I think they are both running on Eclipse, and indeed there is.
So I installed it, and now I have rather a better idea of what it does:
It takes the comment lines out of your program and presents them in a format and filetype that can be understood by managers with a little technical ability.

Bingo! Sweet!

What's really nice with knowing that doxygen will be used later, is adding a few extra doxygen comment lines to enhance the format to something usable for those with technical ability.

That's exactly what it's for in my case. The source code is my documentation but the managers want little books they can read, with pictures.

 

Bingo! Sweet!

What's really nice with knowing that doxygen will be used later, is adding a few extra doxygen comment lines to enhance the format to something usable for those with technical ability.

That's exactly what it's for in my case. The source code is my documentation but the managers want little books they can read, with pictures.

So far, I have made it produce either:
nothing at all
or:
A complete verbatim copy of all my .h files.

I was just about to have another look at your examples.

 

Here is the file used with the MPLAB plugin.

It also works with the command line Linux doxygen executable to made the documentation folders.

The INPUT and maybe OUTPUT lines will need to be changed.

 

If I set "EXTRACT ALL" to "NO" it produces no output at all.
if I set "EXTRACT ALL" to "YES" it produces entries for every function, even those for which there is no documentation, which is 123 pages, mostly of nonsense.
I can't find a start to the html, and a lot of the links it produces don't work.
From what I have read, if I set "EXTRACT ALL" to "NO" it should only document the comments that start /**.
I think I must be missing something obvious.

 

If I set "EXTRACT ALL" to "NO" it produces no output at all.
if I set "EXTRACT ALL" to "YES" it produces entries for every function, even those for which there is no documentation, which is 123 pages, mostly of nonsense.
I can't find a start to the html, and a lot of the links it produces don't work.
From what I have read, if I set "EXTRACT ALL" to "NO" it should only document the comments that start /**.
I think I must be missing something obvious.

Go to the generated html directory and select the standard html root file, index.html to open in the browser.

If you say NO, then logically in this programs logic, you must tell it what files you want documentation, with \file
https://www.doxygen.nl/manual/commands.html#cmdfile

https://www.doxygen.nl/manual/faq.html

When I set EXTRACT_ALL to NO none of my functions are shown in the documentation.
In order for global functions, variables, enums, typedefs, and defines to be documented you should document the file in which these commands are located using a comment block containing a \file (or @file) command.

Alternatively, you can put all members in a group (or topic) using the \ingroup command and then document the group using a comment block containing the \defgroup command.

Set to NO with \file commands added in main.c and vconfig.h

vconfig.h



Only generates docs for those two files.


generated docs for vconfig.h

 

If you say NO, then logically, you must tell it what files you want documentation, with \file

OK. Yes. It's in the FAQs. It's getting late here. . . . . .

 

OK. Yes. It's in the FAQs. It's getting late here. . . . . .

Get some sleep...

 

I’m getting the hang of it now.
Do you use the .rtf output? If so, have you noticed that it makes a mess of any Unicode characters. If I put an ohm sign or degrees C in the comment like it comes out as a complete muddle or several characters.

 

I've only used the html pages as I don't use MS word.

INPUT_ENCODING
This tag can be used to specify the character encoding of the source files that Doxygen parses. Internally Doxygen uses the UTF-8 encoding. Doxygen uses libiconv (or the iconv built into libc) for the transcoding. See the libiconv documentation for the list of possible encodings.

Try changing the INPUT_ENCODING to ISO-8859-1 or something compatible.
https://www.gnu.org/software/libiconv/