Subject: bug#35595: subr.el Commentary + Code sections

From: Van L <[email-masked]>
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.