[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: DOC_STRINGS_IN_COMMENTS
From: |
Miles Bader |
Subject: |
Re: DOC_STRINGS_IN_COMMENTS |
Date: |
16 Oct 2001 02:37:37 +0900 |
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"
- DOC_STRINGS_IN_COMMENTS, Miles Bader, 2001/10/14
- Re: DOC_STRINGS_IN_COMMENTS, Gerd Moellmann, 2001/10/14
- Re: DOC_STRINGS_IN_COMMENTS, Miles Bader, 2001/10/14
- Re: DOC_STRINGS_IN_COMMENTS, Gerd Moellmann, 2001/10/15
- Re: DOC_STRINGS_IN_COMMENTS,
Miles Bader <=
- Re: DOC_STRINGS_IN_COMMENTS, Richard Stallman, 2001/10/16
- Re: DOC_STRINGS_IN_COMMENTS, Gerd Moellmann, 2001/10/16
- Re: DOC_STRINGS_IN_COMMENTS, Miles Bader, 2001/10/16
- Re: DOC_STRINGS_IN_COMMENTS, Miles Bader, 2001/10/16
- Re: DOC_STRINGS_IN_COMMENTS, Pavel Janík, 2001/10/16
- Re: DOC_STRINGS_IN_COMMENTS, Miles Bader, 2001/10/16
- Re: DOC_STRINGS_IN_COMMENTS, Richard Stallman, 2001/10/16
- Re: DOC_STRINGS_IN_COMMENTS, Miles Bader, 2001/10/16
- Re: DOC_STRINGS_IN_COMMENTS, Gerd Moellmann, 2001/10/16
Re: DOC_STRINGS_IN_COMMENTS, Pavel Janík, 2001/10/14