pomd4c

pomd4c is a lightweight doc generator for small, simple, projects.

It's licensed under the MIT license.

ℹ️ for a complete example, see the the API docs, which are generated by pomd4c from its own source.

(for a real-world example, see the libbsat API docs or example docs)

The rules are:

• Special comments are output verbatim (with minor exceptions).
• C definitions/declarations following comments are wrapped in C code fences.
• Optionally, you can adjust the output using a postprocessing script.

That's it!

You can test it out like so:

gcc ./pomd4c.c -o ./pomd4c \
    && ./pomd4c ./pomd4c.c > ./API.md

(A Makefile is included — make help for more info)

👈 Example

input.c

/** #### Doc Comment Header!
 *
 * Doc comments start with `'/'`, `'*'`, `'*'`.
 *
 * Anything inside is emitted verbatim.
 * For example, here's a list:
 *
 *  - regular ol'
 *  - markdown list
 *
 * > :warning: **NOTE**: _This message is important!_
 *
 * ----
 *
 * You get the idea.
 *
 * Anything that _immediately follows_ a doc comment is
 * wrapped in C code fences, like so:
 */
int my_func(uint32_t flags, const char* msg);

output.md

Doc Comment Header!

Doc comments start with '/', '*', '*'.

Anything inside is emitted verbatim. For example, here's a list:

• regular ol'
• markdown list

⚠️ NOTE: This message is important!

---

You get the idea.

Anything that immediately follows a doc comment is wrapped in C code fences, like so:

int my_func(uint32_t flags, const char* msg);

Usage

pomd4c 0.10.0
USAGE: ./pomd4c [OPTIONS] FILE1 [FILE2...FILEN]

OPTIONS:
 -h	Usage info (this)
 -v	Verbosity (more times == more verbose)
 -p	Post-process output script (default: none)
 -e	Specify a postprocessor env parameter (multiple ok)
   	(e.g.: pomd4c -e 'my_key=my_value')

POSTPROCESSING

  By default, pomd4c simply buffers the contents of special comments
  and any C entitity that follows immediately afterwards. Output is
  direct to STDOUT.

  To facilitate additional formatting and file handling, pomd4c can
  optionally offload the last step — formatting and file writing —
  to an auxiliary process, e.g.:

    $ pomd4c -p /path/to/my/script ./my_source.c

  The process receives two arguments, "COMMENT" and "BODY": they are
  paths to temp files containing the comment data and the subsequent
  C entity (if present). STDOUT and STDERR are left open (mind your
  STDOUT if you're leveraging redirects!). Parameters and metadata
  are provided through the env. C entities are NOT wrapped in code
  fences.


POSTPROCESS ENV

  pomd4c provides some limited metadata to postprocessing scripts, by
  way of env vars with a "POMD4C_" prefix, e.g.:

      POMD4C_VERSION:   the current pomd4c version...
      POMD4C_SOURCE:    the path (absolute) to the current source
      POMD4C_SKIP_COLS: number of comment columns to skip   3

  The environment can be further extended using the -e option, which
  takes arguments in the format "NAME=value" and creates environment
  variables with a POMD4C_P_ prefix, e.g.:
      $ pomd4c -p ./my-script.sh -e my_param=value ...

  Will set the env var POMD4C_P_MY_PARAM equal to "value"


ENVIRONMENT

  Some pomd4c behavior can be further customized via env vars:

    NAME:              DESRIPTION:                         DEFAULT:
    POMD4C_SKIP_COLS   Number of comment columns to skip   3