helpmemake.awk

#!/bin/env gawk
# Script to extract make-style documentation comments for various targets in the
# Shodan build system.
#
# Documentation comments are of the form:
#
#   ## Short one-line summary comment
#   #
#   # Additional descriptive text.
#   target:
#
# Note that the target definition terminates the doc-comment!
#
## Theory of operation
#
# This script operates in two passes: first it accumulates all doc comments from
# the files specified on the command line, and then it looks up the target in
# the `targetname` environment variable for the name of the target to extract
# docs for.
#
# If `targetname` is empty or a target we didn't find, hmm will output a list of
# targets that have doccomments instead.

BEGIN {
  debug = 0;
}

function flush_comment() {
  doc_accumulator = "";
  in_doccomment = 0;
}

# Start of a doc-comment. This enables accumulation of a doc-comment into the
# accumulator in the later patterns.
/^## / {
  in_doccomment = 1;
  doc_accumulator = substr($0, 3);

  doc_filename = ARGV[ARGIND];
  sub(ENVIRON["ROOTDIR"] "/", "", doc_filename);
}

# Continuation of a doc-comment
in_doccomment && /^# / {
  comment = substr($0, 2);
  doc_accumulator = sprintf("%s\n%s", doc_accumulator, comment);
}

# Doc-comment empty line, so we can separate paragraphs.
in_doccomment && /^#$/ {
  doc_accumulator = sprintf("%s\n", doc_accumulator);
}

# Doc-comment proper terminator -- the target name.
in_doccomment && /^[^#]*:/ {
  target = substr($1, 0, index($1, ":") - 1);
  docs[target] = doc_accumulator;
  files[target] = doc_filename;
  flush_comment();
}

END {
  targetname = ENVIRON["targetname"];

  if (targetname in docs) {
    print "";
    print targetname ": (defined in " files[targetname] ")";
    print docs[targetname];
    print "";
    exit(0);
  }

  # GAWK extension: sort the docs array keys into the sorted_targets array
  asorti(docs, sorted_targets)

  for (target in sorted_targets) {
    printf("%s\n", sorted_targets[target]);
  }
}