GNU bug report logs - #35595
subr.el Commentary + Code sections

Previous Next

Full log

View this message in rfc822 format

From: Van L <van <at> scratch.space>
To: Noam Postavsky <npostavs <at> gmail.com>
Cc: 35595 <at> debbugs.gnu.org
Subject: bug#35595: subr.el Commentary + Code sections
Date: Thu, 9 May 2019 09:31:19 +1000

> Noam Postavsky writes:
> 
> Sorry, I was a bit terse above.  I was quoting (elisp) Library Headers,
> where it says
> 
>    `;;; Commentary:'
>         This begins introductory comments that explain how the library
>         works.  It should come right after the copying permissions,
>         terminated by a `Change Log', `History' or `Code' comment line.
>         This text is used by the Finder package, so it should make sense
>         in that context.
> 
>    [...]
> 
>    `;;; Code:'
>         This begins the actual code of the program.
> 
> So I'm not sure if the "Beware..." comment belongs under the
> "Commentary" header, perhaps it's better put under the "Code:" header,
> like the comment about declare-function.  And perhaps it makes no sense
> to add these headers in the first place, since subr.el isn't exactly a
> library.

I have no idea how important the "Beware... " comment is. An important enough comment IMO should go on oneline topline WARNING as a wrinkle to be ironed out in time. Perhaps an autoconfiguring function generates the final file that fits ascii-only or wider charsets after environment detection in the early build staging. IMO a familiar pattern of headlines makes sense in any file in or out of the lib. Thanks. I'll make sure I take a first look at (elisp) for norms/conventions before sending what I may mistaken as a fix for what I see is missing.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.