Re: [PATCH] docs: Make automarkup ready for Sphinx 3.1+

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

Em Thu, 8 Oct 2020 03:47:06 +0100
Matthew Wilcox <willy@infradead.org> 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