• Jani Nikula's avatar
    kernel-doc: limit the "section header:" detection to a select few · f624adef
    Jani Nikula authored
    kernel-doc currently identifies anything matching "section header:"
    (specifically a string of word characters and spaces followed by a
    colon) as a new section in the documentation comment, and renders the
    section header accordingly.
    
    Unfortunately, this turns all uses of colon into sections, mostly
    unintentionally. Considering the output, erroneously creating sections
    when not intended is always worse than erroneously not creating sections
    when intended. For example, a line with "http://example.com" turns into
    a "http" heading followed by "//example.com" in normal text style, which
    is quite ugly. OTOH, "WARNING: Beware of the Leopard" is just fine even
    if "WARNING" does not turn into a heading.
    
    It is virtually impossible to change all the kernel-doc comments, either
    way. The compromise is to pick the most commonly used and depended on
    section headers (with variants) and accept them as section headers.
    
    The accepted section headers are, case insensitive:
    
     * description:
     * context:
     * return:
     * returns:
    
    Additionally, case sensitive:
    
     * @return:
    
    All of the above are commonly used in the kernel-doc comments, and will
    result in worse output if not identified as section headers. Also,
    kernel-doc already has some special handling for all of them, so there's
    nothing particularly controversial in adding more special treatment for
    them.
    
    While at it, improve the whitespace handling surrounding section
    names. Do not consider the whitespace as part of the name.
    Signed-off-by: default avatarJani Nikula <jani.nikula@intel.com>
    f624adef
kernel-doc 85.3 KB