linux-kernel - Re: [PATCH] scripts/kernel-doc: handle object-like macros

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <53B16B46.7060101@freescale.com>
Date:	Mon, 30 Jun 2014 16:51:02 +0300
From:	Horia Geantă <horia.geanta@...escale.com>
To:	Randy Dunlap <rdunlap@...radead.org>
CC:	<linux-doc@...r.kernel.org>, <linux-kernel@...r.kernel.org>
Subject: Re: [PATCH] scripts/kernel-doc: handle object-like macros

On 6/29/2014 5:52 AM, Randy Dunlap wrote:
> On 06/23/14 05:15, Horia Geanta wrote:
>> Object-like macros are different than function-like macros:
>> https://gcc.gnu.org/onlinedocs/cpp/Object-like-Macros.html
>> https://gcc.gnu.org/onlinedocs/cpp/Function-like-Macros.html
>>
>> They are not parsed correctly, generating invalid intermediate
>> files (xmls) for cases like:
>>      #define BIT_MASK    (0xFF << BIT_SHIFT)
>> where "OxFF <<" is considered to be parameter type.
>>
>> When parsing, we can differentiate beween these two types of macros by

                                      between.

>> checking whether there is at least one whitespace b/w "#define" and
>> first opening paranthesis.
>
>                  parenthesis.

Thanks, I'll fix both typos in v2.

>
> Where did you see a problem?  I tested the patch and all of the
> Documentation/DocBook/*.xml files are the same without or with the patch.
>

Indeed, right now there is no kernel-doc for "object-like" macros in 
Docbook.

I am preparing documentation for not-yet-upstreamed code in 
drivers/crypto/caam and I thought it would be useful to use kernel-doc 
for some of the #defines.

Doc would look like this (no @param list, no "Return" section, only a 
description):

/**
  * DEFAULT_SEC_ERA - the default value for the SEC era in case the user
  * provides an unsupported value.
  */
#define DEFAULT_SEC_ERA 6

Regards,
Horia


--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@...r.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/