Em Thu, 8 Oct 2020 03:47:06 +0100
Matthew Wilcox <willy@xxxxxxxxxxxxx> escreveu:
> On Thu, Oct 08, 2020 at 02:15:24AM +0000, Nícolas F. R. A. Prado wrote:
> > > I have a feature request ... could you automarkup NULL as being
> > > :c:macro?
> > > Or maybe just anything matching \<[[:upper:]_[:digit:]]*\>
> > > (i may have my regex syntax confused ... a word composed of any
> > > arrangement of upper-case, digits and underscores.)
> >
> > I think what you are suggesting are two separate things.
> >
> > For NULL, what you're interested in is that it appears in a monospaced font, as
> > if written ``NULL``, right? As I don't think a cross-reference to "the NULL
> > macro definition" would make much sense.
> >
> > While "anything containing only upper-case, digits and underscores" would
> > actually be for cross-referencing to the definition of the macro symbol in
> > question, right?
>
> Well, maybe! What I'd really like is to remove all the markup from
> xarray.rst. Jon managed to get rid of most of it with the (), but
> there's still markup on:
>
> LONG_MAX
> NULL
> -EBUSY
> true
> XA_MARK_[012]
> XA_FLAGS_*
> ENOMEM
> EINVAL
>
> I'm not sure there's much that automarkup can do about ``true``, but all
> the others fit the all-caps-and-underscore-and-digits pattern.
>
> I don't know how much we want errnos to link to anything in particular.
> So maybe split these into 'well-known' (eg defined by ANSI C or POSIX)
> definitions and things which are local macros:
>
> LONG_MAX
> NULL
> -EBUSY
> ENOMEM
> EINVAL
Yeah, a nice improvement would be to auto-markup error codes and NULL as
literal blocks.
>
> vs
>
> XA_MARK_[012]
> XA_FLAGS_*
Actually, things that end with an * (but doesn't start with an *)
are good candidates for being literals - although extra care should
be taken on such case, as parsing those automatically will likely hit
lots of false-positives.
> I'm willing to add more inline kernel-doc to get this to work better.
Why? inline kernel-doc should be evaluated just like normal blocks.
Right now, kernel-doc handles constants like NULL and XA_FLAGS_* using
two ways:
%FOO
or
``FOO``
The regex for those are:
my $type_constant = '\b``([^\`]+)``\b';
my $type_constant2 = '\%([-_\w]+)';
In other words, "%FOO" should not contain any symbol, except for
'-' and '_'.
If there is any other symbol, like in "XA_FLAGS_*", the alternative
syntax is needed.
No matter if you use inline or block definitions, the same regexes
are used.
> Or even convert #defines to enums ... whatever gets this working better.
Using enums where possible[1] is nicer, IMHO.
[1] enums shouldn't be used on uAPI, as its size depends on the C
compiler implementation.
Thanks,
Mauro
