netdev - RE: [PATCH net-next] tools: ynl-gen: generate docs for <name>_max/

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]

Date: Wed, 14 Jun 2023 22:11:38 +0000
From: "Kubalewski, Arkadiusz" <arkadiusz.kubalewski@...el.com>
To: Jakub Kicinski <kuba@...nel.org>
CC: "netdev@...r.kernel.org" <netdev@...r.kernel.org>,
	"linux-kernel@...r.kernel.org" <linux-kernel@...r.kernel.org>,
	"davem@...emloft.net" <davem@...emloft.net>, "pabeni@...hat.com"
	<pabeni@...hat.com>, "edumazet@...gle.com" <edumazet@...gle.com>,
	"chuck.lever@...cle.com" <chuck.lever@...cle.com>
Subject: RE: [PATCH net-next] tools: ynl-gen: generate docs for
 <name>_max/_mask enums

>From: Jakub Kicinski <kuba@...nel.org>
>Sent: Wednesday, June 14, 2023 7:39 PM
>
>On Wed, 14 Jun 2023 12:48:14 +0000 Kubalewski, Arkadiusz wrote:
>> >From: Jakub Kicinski <kuba@...nel.org>
>> >Sent: Wednesday, June 14, 2023 2:59 AM
>> >
>> >On Wed, 14 Jun 2023 01:17:09 +0200 Arkadiusz Kubalewski wrote:
>> >> Including ynl generated uapi header files into source kerneldocs
>> >> (rst files in Documentation/) produces warnings during documentation
>> >> builds (i.e. make htmldocs)
>> >>
>> >> Prevent warnings by generating also description for enums where
>> >> rander_max was selected.
>> >
>> >Do you reckon that documenting the meta-values makes sense, or should
>> >we throw a:
>> >
>> >/* private: */
>> >
>>
>> Most probably it doesn't..
>> Tried this:
>> /*
>>  [ other values description ]
>>  * private:
>>  * @__<NAME>_MAX
>>  */
>> and this:
>> /*
>>  [ other values description ]
>>  * private: @__<NAME>_MAX
>>  */
>>
>> Both are not working as we would expect.
>>
>> Do you mean to have double comments for enums? like:
>> /*
>>  [ other values description ]
>>  */
>> /*
>>  * private:
>>  * @__<NAME>_MAX
>>  */
>>
>> >comment in front of them so that kdoc ignores them? Does user space
>> >have any use for those? If we want to document them...
>>
>> Hmm, do you recall where I can find proper format of such ignore enum
>comment
>> for kdoc generation?
>> Or maybe we need to also submit patch to some kdoc build process to
>actually
>> change the current behavior?
>
>It's explained in the kdoc documentation :(
>https://docs.kernel.org/doc-guide/kernel-doc.html#members


Thanks for pointing this, but it doesn't work :/

I tried described format but still ./scripts/kernel-doc warns about it.
Same as 'make htmldocs' does, as it uses ./scripts/kernel-doc

Also, if the enum is not described in the header, the docs produced by
the 'make htmldocs' would list the enum with the comment "undescribed".

It seems we need fixing:
- prevent warning from ./scripts/kernel-doc, so enums marked as "private:"
  would not warn
- generate __<ENUM_NAME>_MAX while marking them as "/* private: */"
- add some kind of "pattern exclude" directive/mechanics for generating
  docs with sphinx

Does it make sense?
TBH, not yet sure if all above are possible..

Thank you!
Arkadiusz