Similarly, I try to bake the documentation directly into the code. Eg (from a shell):

  OPTION(*line=='[',"[EXPR]","the result of evaluating EXPR as a math expression (see -?m)")
    { ... }
  qsh -?s | grep -F '$['
      '$[EXPR]': the result of evaluating EXPR as a math expression (see -?m)

So OPTION does triple duty as 'comments', documentation, and the actual test for what kind of substitution is being parsed. This tends to be at the mercy of code structure though.