Re: doc snarfing ...

[Bruce Korb]

Jim Blandy wrote:

> I actually got really fed up with the snarfer and wrote up most of a
> replacement in C.  It was working fine, until it started pulling out
> info on functions that were in the disabled branch of a "#if".  Then I
> realized I would have to implement #include, #define, and full CPP
> conditionals (with expression evaluation!) to do the job accurately.

Hi Jim,

So did I (become fed up).  For this and other reasons.
If you have a copy of AutoGen installed (ha, ha), take
a look at:

   ag-info-doc > AutoGen Template > \
      AutoGen Scheme Functions > `dne' - "Do Not Edit" warning

this is on-line at:
     http://www.gnu.org/software/autogen/doc/autogen_3.html#SEC33

Next, look at the sources:
   agen5/expr.h:
        extern SCM ag_scm_dne( SCM, SCM );

   agen5/expr.ini:
      static const char s_dne[] = "dne";
      gh_new_procedure( (char*)s_dne,
                        ag_scm_dne, 1, 1, 0 );

and realize that it all gets generated from this:

/*=gfunc dne
 *
 * what:  '"Do Not Edit" warning'
 *
 * exparg: prefix, string for starting each output line
 * exparg: first_prefix, for the first output line, opt
 *
 * doc:  Generate a "DO NOT EDIT" or "EDIT WITH CARE" warning string.
 *       Which depends on whether or not the @code{--writable} command line
 *       option was set.  The argument is a per-line string prefix.
 *       The optional second argument is a first-line prefix and,
 *       in read-only mode, activates the editor hints:
 *       @*
 *       @example
 *       -*- buffer-read-only: t -*- vi: set ro:
 *       @end example
=*/

And conditional compilation is accommodated via:

  funcDef.c:/*=macfunc DEBUG, ifdef DEBUG

(not a scheme function, obviously :-)

> The advantage of using the real CPP is that you're seeing exactly what
> the compiler's going to see.
> 
> If we're going to throw out CPP, I think we should scrap the whole
> idea of snarfing altogether.  Putting that info in a separate file,
> whose syntax we can choose, would settle the issue permanently.  Not
> that having the info right next to the function definition isn't
> deliciously convenient, but it isn't really C, and we should expect to
> suffer.

I have found the pain threshhold way below the pain of concurrent
update issues involved with separate documentation.  :-)