From: 046-301-5902@kylheku.com   
      
   On 2025-12-22, Keith Thompson  wrote:   
   > Tim Rentsch  writes:   
   >> antispam@fricas.org (Waldek Hebisch) writes:   
   >>> Tim Rentsch  wrote:   
   >>>> James Kuyper  writes:   
   > [...]   
   >>>>> Note: in C2023, the [predefined macro names] section says:  "Any other   
   >>>>> predefined macro names:  shall begin with a leading underscore   
   >>>>> followed by an uppercase letter;  or, a second underscore...".  For   
   >>>>> earlier versions of the standard, user code should avoid using such   
   >>>>> identifiers because they were reserved for all purposes, but that's no   
   >>>>> longer the case.  Now, they should be avoided because they may be   
   >>>>> pre-defined by the implementation, which means that any attempt to use   
   >>>>> them might have unpredictable results.   
   >>>>   
   >>>> That's right in the sense that if the implementation is unknown then   
   >>>> unexpected results may occur.  However, if the implementation is   
   >>>> known, then we can find out what results are expected by consulting   
   >>>> the implementation's documentation for extensions, since any such   
   >>>> macro name must qualify as an extension, and so much be documented.   
   >>>   
   >>> Hmm, looking at '/usr/include/string.h' on my machine I see definitions   
   >>> of things like   
   >>>   
   >>> __GLIBC_INTERNAL_STARTING_HEADER_IMPLEMENTATION   
   >>> __need_size_t   
   >>>   
   >>> and lot of similar things.  I do not recall seeing any user   
   >>> documentation listing them.  Does this mean that gcc+glibc   
   >>> is noncompilant in this aspect?   
   >>   
   >> I think it's reasonable to say that the appearance of a macro   
   >> name being #define'd in a standard header qualifies as   
   >> documenting the name being #define'd.   
   >   
   > I disagree.  I don't think it's reasonable to say that.   
   >   
   > Headers are not documentation.   
      
   It makes no sense for a file to be a document, just because it is   
   part of the implementation, ipso facto.   
      
   A binary executable contains text written in a machine language that   
   we can read and understand---some people without the aid of a   
   disassembler, even. It does not therefore follow that a compiler   
   executable is documentation.   
      
   No artifact delivered by the implementor is part of the documentation   
   unless it is designated as such.   
      
   A header file is documentation if the implementor indicates it as a   
   document, otherwise not. And then, it may be that only certain   
   designated and delimited parts of the header file are indicated as   
   documentation. For instance, some other document may direct the reader   
   to read the block comments in a certain header file. Then only block   
   comments are documentation, and not any definitions outside of comments.   
      
   --   
   TXR Programming Language: http://nongnu.org/txr   
   Cygnal: Cygwin Native Application Library: http://kylheku.com/cygnal   
   Mastodon: @Kazinator@mstdn.ca   
      
   --- SoupGate-Win32 v1.05   
    * Origin: you cannot sedate... all the things you hate (1:229/2)