github-mirror/linux
1
0
Fork 0
mirror of https://github.com/torvalds/linux.git synced 2026-06-05 04:56:13 +02:00
Code Issues Actions Packages Projects Releases Wiki Activity Graph

tools: ynl-gen: de-kdocify enums with no doc for entries

Browse Source 
Sometimes the names of the enum entries are self-explanatory
or come from standards. Forcing authors to write trivial kdoc
for each of such entries seems unreasonable, but kdoc would
complain about undocumented entries.

Detect enums which only have documentation for the entire
type and no documentation for entries. Render their doc
as a plain comment.

Link: https://patch.msgid.link/20241103165314.1631237-1-kuba@kernel.org
Signed-off-by: Jakub Kicinski <kuba@kernel.org>
This commit is contained in:
Jakub Kicinski 2024-11-03 08:53:14 -08:00
parent 0a2cdeeae9
commit 690e50dd69
3 changed files with 19 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
include/uapi/linux/dpll.h
View File

@ -79,13 +79,13 @@ enum dpll_lock_status_error {
DPLL_LOCK_STATUS_ERROR_MAX = (__DPLL_LOCK_STATUS_ERROR_MAX - 1)
};
/**
* enum dpll_clock_quality_level - level of quality of a clock device. This
* mainly applies when the dpll lock-status is DPLL_LOCK_STATUS_HOLDOVER. The
* current list is defined according to the table 11-7 contained in ITU-T
* G.8264/Y.1364 document. One may extend this list freely by other ITU-T
* defined clock qualities, or different ones defined by another
* standardization body (for those, please use different prefix).
/*
* level of quality of a clock device. This mainly applies when the dpll
* lock-status is DPLL_LOCK_STATUS_HOLDOVER. The current list is defined
* according to the table 11-7 contained in ITU-T G.8264/Y.1364 document. One
* may extend this list freely by other ITU-T defined clock qualities, or
* different ones defined by another standardization body (for those, please
* use different prefix).
*/
enum dpll_clock_quality_level {
DPLL_CLOCK_QUALITY_LEVEL_ITU_OPT1_PRC = 1,

3
tools/net/ynl/lib/nlspec.py
View File

@ -131,6 +131,9 @@ class SpecEnumSet(SpecElement):
def has_doc(self):
if 'doc' in self.yaml:
return True
return self.has_entry_doc()
def has_entry_doc(self):
for entry in self.entries.values():
if entry.has_doc():
return True

14
tools/net/ynl/ynl-gen-c.py
View File

@ -2437,11 +2437,15 @@ def render_uapi(family, cw):
enum = family.consts[const['name']]
if enum.has_doc():
cw.p('/**')
doc = ''
if 'doc' in enum:
doc = ' - ' + enum['doc']
cw.write_doc_line(enum.enum_name + doc)
if enum.has_entry_doc():
cw.p('/**')
doc = ''
if 'doc' in enum:
doc = ' - ' + enum['doc']
cw.write_doc_line(enum.enum_name + doc)
else:
cw.p('/*')
cw.write_doc_line(enum['doc'], indent=False)
for entry in enum.entries.values():
if entry.has_doc():
doc = '@' + entry.c_name + ': ' + entry['doc']