This is the mail archive of the
libc-help@sourceware.org
mailing list for the glibc project.
[Standards References] @def vs. @item
- From: Rical Jasan <ricaljasan at pacific dot net>
- To: "libc-help at sourceware dot org" <libc-help at sourceware dot org>
- Date: Wed, 19 Oct 2016 01:01:24 -0700
- Subject: [Standards References] @def vs. @item
- Authentication-results: sourceware.org; auth=none
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