This is the mail archive of the libc-help@sourceware.org mailing list for the glibc project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

[Standards References] @def vs. @item


Would anyone be opposed to defining new @def macros for @items that
deserve header and standards annotations?

One issue I'm running into is that all @def* macros clearly have the
potential for being annotated with the header and standard the defined
thing comes from, but not all @items do.  For example, @item may be
generically used to create a bullet while discussing points about a
certain topic or to generate lists, but many @items are also used to
describe lists of macros (e.g., return values to test for) or struct
members, which do deserve some annotation.

There are already @def macros for preprocessor macros, so that may not
require anything new, but I haven't experimented with
supplanting/augmenting the use of @item in that context.  For struct
members, you might say the header/standard of the struct applies to the
members, but that isn't always the case---sometimes members are declared
conditionally (or at least their types, for example).

The goal I have in mind is to make it straightforward to guarantee
everything that needs annotation has it, perhaps with a script that does
something like (pseudo-Perl):

  $lstln2, $lstln, $line;
  while ($line = <STDIN>) {
    if ($line =~ /^\@def/) {
      if ($lstln !~ $stdcmt
          || $lstln2 !~ $hdrcmt)
        {
          ERROR;
        }
      # else potential for /anything/
    }
    $lstln2 = $lstln;
    $lstln = $line;
  }

The problem with @item is that we can never know whether it should be
annotated or not.

Thanks,
Rical


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]