Re: [comp.emacs.xemacs] Documenting elisp code
First of all sorry for the late reply.
On 3 Nov 2001, Stephen J. Turnbull wrote:
>>>>> "APA" == Adrian Aichner
<Adrian.Aichner(a)t-online.de> writes:
APA> Any comments?
APA> From: Jarl Friis <jarl(a)diku.dk>
jf> according to the "elisp refference" (lispref.info) there are
jf> som elisp commenting tips. It describes when to use one, two,
jf> three, and four semicolons and where they should be put and
jf> alligned.
jf> But those tips don't fit to well with the tips given in the
jf> "library headers" section (same info-file) , here ";;" is
used
jf> where, according to the commenting tips, ";;;" should be
jf> used. similarily ";;;" is used where ";;;;" should be
used.
jf> The outline-mode seem to follow the library header tips, and
jf> *not* the elisp commenting tips.
Do you mean outline-mode _in use_ groks the library header tips? Or
that the source code is written in conformance with them?
I ment that the outline-mode _in use_ comply with the library header
tips. But now you'r asking the source code does also comply with the
library tips (not the elisp coding tips). One can of course easily change
the behaviour to comply with the elisp coding tips instead.
But I guess what is wanted is documentation that is consistent, and an
outline-mode behaviour that comply with that documentation.
jf> Why are the tips so contradicting?
Probably because they were written by different people.
OK, I don't mind rewriting one of them, now I just ask for opinions, which
one is preferable:
elisp coding tips (suggests use of one, two, three, and four ';' )
OR
library header tips (suggests use of one, two, and three ';' )
Personally I prefer the elisp coding tips. Yes, I know most of packages
are written according to library header tips.
For my money, the lisp-mnt library explicitly supports the "library
header" approach, I think there are other tools (maybe outline mode?)
that do too. What does emacs-lisp-mode do? If it is compatible with
lisp-mnt style, we should settle on that style.
OK, so I guess you (to avoid recoding parts of lisp-mnt) suggest the
library header tips
Jarl