cdoc.re.c

• Description
• Function Summary
• Function Definitions
• License

Description

Static documentation generator for one C translation unit. This is not a full C context-free grammar decoder; it is limited to regular grammar. Remapping with the pre-processor, complex types, K&R style function definitions, trigraphs, are confusing to it. It just guesses based on reasonable modern coding-standards. However, it assumes that capital latin letters underscores are concatenation commands for the pre-processor, such that A_BC_(foo,bar) is transformed into <A>foo<BC>bar.

In keeping with Javadoc and Doxygen, documentation commands are / **… (together) and are ended with *…/, but not / *…* /. Accounts for asterisks at the start of a line, (Kernel comments,) or asterisks on both sides, (ASCII art?) Documentation appearing at most two lines above typedef, tag (struct, enum, union,) data, and functions, is associated therewith; everything else is automatically inserted into the description. Multiple documentation on the same command is appended. Two hard returns is a paragraph. The big difference is the fixed @param notation; now it has to be followed by a braced list, @param[a, b] Concatenates both..

Supports some Markdown commands included in the documentation,

• \ escapes _~!@<>[] and "`"; "`" can not be represented in math/code, (multiple escapes aren't supported); in paragraph mode, except in ambiguous cases, the only ones that are needed are \` and \_;
• _emphasised_: emphasised;
• `code/math`: code/math;
• start lists with \* (including spaces) and end with a new paragraph; these are simple, can be anywhere and don't nest;
• \" (and optionally a space) causes all the line after to be pre-formatted;
• Escapes included for convenience: \, " " non-breaking thin space, \O "Ο" Bachmann–Landau notation, (but really capital omicron because not many fonts have a shape for code-point 120030,) \Theta "Θ", \Omega "Ω", \times "×", \cdot "·".
• ~ " " non-breaking space;
• <url>: relative URIs must have a slash or a dot to distinguish it from text;
• <Source, 1999, pp. 1-2>: citation, searches on Google scholar;
• <fn:<function>>: function reference;
• <tag:<tag>>: struct, union, or enum (tag) reference;
• <typedef:<typedef>>: typedef reference;
• <data:<identifier>>: data reference;
• [The link text](url): link, Markdown doesn't like {}[]() in text;
• ![Caption text](url.image): image, same;
• a local include directive has a documentation comment immediately after that reads only \include, it will also be included in the documentation.

Each-block-tags separate the documentation until the next paragraph or until the next each-block-tag, and specify a specific documentation structure. Each-block-tags that overlap are concatenated in the file order. Not all of these are applicable for all segments of text. These are:

• @subtitle: only makes sense for preamble, (it doesn't matter what case one writes it, but multiple are concatenated using semicolons);
• @abstract: tl;dr appearing first;
• @param[<param1>[, ...]]: parameters, (multiple are concatenated using spaces, so this really should be sentence case);
• @author (commas);
• @std: standard, eg, @std GNU-C99, (semicolons);
• @depend: dependancy, (semicolons);
• @fixme: something doesn't work as expected, (spaces);
• @return: normal function return, (spaces);
• @throws[<exception1>[, ...]]: exceptional function return; C doesn't have native exceptions, so @throws means whatever one desires; perhaps a null pointer or false is returned and errno is set to exception1;
• @implements: C doesn't have the concept of implements, but we would say that a function having a prototype of (int (*)(const void *, const void *)) implements bsearch and qsort;
• @order: comments about the run-time or space;
• and @allow, the latter being to allow static functions or data in the documentation, which are usually culled.

If one sets md as output, it goes to GitHub Markdown that is specifically visible on the GitHub page, (including working anchor links on browsers > 2000.) This is not the Markdown supported in the documentation.

• Standard:
  C89
• Dependancies:
  re2c
• Caveat:
  Prototype function parameters ignore const. Documentation on prototypes. Links to non-documented code which sometimes doesn't show up, work without error, and create broken links. A fixme with no args disappears; we should NOT check if the string is empty for these values. Documentation on global variables is not output.

Function Summary

Modifiers	Function Name	Argument List
enum debug	cdoc_get_debug
enum format	cdoc_get_format
const char *	cdoc_get_input
const char *	cdoc_get_output

Function Definitions

cdoc_get_debug

enum debug cdoc_get_debug(void)

• Return:
  Whether the command-line was set.

cdoc_get_format

enum format cdoc_get_format(void)

• Return:
  What format the output was specified to be in enum format. If there was no output format specified, guess.

cdoc_get_input

const char *cdoc_get_input(void)

• Return:
  The input filename.

cdoc_get_output

const char *cdoc_get_output(void)

• Return:
  The output filename.

License

2019 Neil Edelman, distributed under the terms of the MIT License.