lkml.org 
[lkml]   [2019]   [Apr]   [5]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
Date
From
SubjectRe: [PATCH] kernel-doc: Let backtick and backslash escape percent sign
On Fri, Apr 05, 2019 at 02:18:20PM -0700, Sean Christopherson wrote:
> There are a handful of instances where kernel doc comments want an
> actual '%' in the final output, e.g. vsnprintf() wants to display "%n"
> and "%p" to document format specifiers, and assembly functions that use
> a custom call ABI may want to document their register usage, e.g. %eax.
>
> Because kernel-doc unconditionally interprets '%' followed by a word
> character as a constant definition, i.e. %CONST, it's impossible to get
> an actual '%\w' when kernel-doc is used to translate comments into rst
> format. Treat backtick and backlash as escaping '%', the former to
> handle '%' in a ``LITERAL``, and the latter to allow '%' when using
> standard formatting.
>
> An alternative option would be to define a fancier set of rules for
> interpreting '%' so that explicit escaping would not be required. For
> example, require "%CONST" to be preceded by a recognized set of
> characters, e.g. whitespace, opening parenthesis, etc... But the list
> of recognized characters is quite large even in the current code base,
> and using '\' to escape is more common and intuitive, i.e. most people
> will naturally try doing "\%..." to get the desired formatting, whereas
> losing %CONST formatting because of an unrecognized character is likely
> to cause confusion.

Would it make sense to have %% turn into % rather than forcing quotation
marks?

\
 
 \ /
  Last update: 2019-04-06 01:11    [W:0.062 / U:0.712 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site