[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#35595: subr.el Commentary + Code sections
From: |
Van L |
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.