Re: DOC_STRINGS_IN_COMMENTS

[Miles Bader]

address@hidden (Gerd Moellmann) writes:
> Hm, how's 
> 
>     DEFUN ("foo", ..., doc: /* blah blah blah */
>         (args)
> 
> better than 
> 
>     DEFUN ("foo", ... /* blah blah blah */
>            (args))

You missed several important puncuation elements; it's actually:

    DEFUN ("foo", ..., doc: /* blah blah blah */)
       (args)
       Type args;
    {
    }

vs:

     DEFUN ("foo", ..., /* blah blah blah */
            (args))
       Type args;
    {
    }

The former (`doc:' case), has the following advantages:

  (1) The argument list is grouped with the argument type declarations,
      as in a normal C function, not separated by an additional
      end-paren (the indentation that c-mode uses reflects this too).

  (2) Each logical component of the DEFUN is separated by a comma, as is
      natural for C programmers when using macros -- the current
      doc-in-comment style instead puts the doc-comment before the
      argument list _without_ any separator, which is quite unnatural.

      Comments in _general_ can be placed anywhere, but you don't want
      people to think of this as just any-old-comment, because it's not,
      it's placement is significant, and it should be treated like a
      real syntactic element.  [Note this is actually an additional
      benefit of using `doc:' -- it identifies the doc-comment as being
      something special, not just an ordinary comment.]

  (3) It's source-compatible with the old DEFUN style [you seem to have
      converted every function, so I guess this isn't so much of an
      advantage anymore].

The new the new doc-in-comment style throws out these advantages,
and feels more much more kludgey than the old DEFUN.

This wouldn't be a big deal if it were a rarely used macro, but
unfortunately, it applies to _every_ exported function in emacs, and
adds a small but pervasive bit of ugliness to the code.

Note that I'm not saying this `doc:' method is pretty, merely that it is
better than the alternative.

> ?  Anyway, I think it's now too late.

It's never too late...  [after all, you seem to have converted the whole
code base in a very short time, so I guess you used some script.]

-Miles
-- 
"1971 pickup truck; will trade for guns"