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?
