Re: [PATCH v3] docs-rst: ignore arguments on macro definitions
Am 08.09.2016 um 13:40 schrieb Mauro Carvalho Chehab: > Hi Jon/Markus, > > Em Mon, 29 Aug 2016 16:12:39 +0200 > Markus Heiser escreveu: > >> Am 29.08.2016 um 15:13 schrieb Mauro Carvalho Chehab >> : >> >>> A macro definition is mapped via .. c:function:: at the >>> ReST markup when using the following kernel-doc tag: >>> >>> /** >>> * DMX_FE_ENTRY - Casts elements in the list of registered >>> * front-ends from the generic type struct list_head >>> * to the type * struct dmx_frontend >>> * >>> * @list: list of struct dmx_frontend >>> */ >>> #define DMX_FE_ENTRY(list) \ >>> list_entry(list, struct dmx_frontend, connectivity_list) >>> >>> However, unlike a function description, the arguments of a macro >>> doesn't contain the data type. >>> >>> This causes warnings when enabling Sphinx on nitkpick mode, >>> like this one: >>> ./drivers/media/dvb-core/demux.h:358: WARNING: c:type reference target >>> not found: list >> >> I think this is a drawback of sphinx's C-domain, using function >> definition for macros also. From the function documentation >> >> """This is also used to describe function-like preprocessor >>macros. The names of the arguments should be given so >>they may be used in the description.""" >> >> I think about to fix the nitpick message for macros (aka function >> directive) in the C-domain extension (we already have). >> >> But for this, I need a rule to distinguish between macros >> and functions ... is the uppercase of the macro name a good >> rule to suppress the nitpick message? Any other suggestions? > > What's the status of the C domain patches meant to fix this issue? > > I managed to fix most warnings on media documents on nitpick mode. > With this patch applied, there are only 21 warnings (and all are > due to the lack of function or struct documentation). I'm about > to patchbomb such fixup series. > > Yet, without this patch, and latest docs-next, there are 20 extra > bogus warnings, due to function parameters: > > ./drivers/media/dvb-core/dvb_ringbuffer.h:121: WARNING: c:type reference > target not found: rbuf > ./drivers/media/dvb-core/dvb_ringbuffer.h:121: WARNING: c:type reference > target not found: offs > ./drivers/media/dvb-core/dvb_ringbuffer.h:130: WARNING: c:type reference > target not found: rbuf > ./drivers/media/dvb-core/dvb_ringbuffer.h:130: WARNING: c:type reference > target not found: num > ./drivers/media/dvb-core/dvb_ringbuffer.h:173: WARNING: c:type reference > target not found: rbuf > ./drivers/media/dvb-core/dvb_ringbuffer.h:173: WARNING: c:type reference > target not found: byte > ./drivers/media/dvb-core/demux.h:358: WARNING: c:type reference target not > found: list > ./include/media/media-device.h:263: WARNING: c:type reference target not > found: mdev > ./include/media/media-device.h:495: WARNING: c:type reference target not > found: mdev > ./include/media/media-device.h:495: WARNING: c:type reference target not > found: udev > ./include/media/media-device.h:495: WARNING: c:type reference target not > found: name > ./include/media/media-entity.h:527: WARNING: c:type reference target not > found: gobj > ./include/media/media-entity.h:536: WARNING: c:type reference target not > found: gobj > ./include/media/media-entity.h:545: WARNING: c:type reference target not > found: gobj > ./include/media/media-entity.h:554: WARNING: c:type reference target not > found: gobj > ./include/media/media-entity.h:563: WARNING: c:type reference target not > found: intf > ./include/media/media-entity.h:1041: WARNING: c:type reference target not > found: entity > ./include/media/media-entity.h:1041: WARNING: c:type reference target not > found: operation > ./include/media/v4l2-ctrls.h:397: WARNING: c:type reference target not found: > hdl > ./include/media/v4l2-ctrls.h:397: WARNING: c:type reference target not found: > nr_of_controls_hint > > So, it would be great if we could either merge this patch or the ones that > Markus did (assuming they're ready for merge). I fixed the remarks of Jon and resend v2 yesterday ... https://www.mail-archive.com/linux-media@vger.kernel.org/msg102259.html sorry, I'am currently in a hurry, may do you like to test the patch, to see if we get rid of those 20 extra bogus warnings? Thanks! -- Markus -- -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v3] docs-rst: ignore arguments on macro definitions
Hi Jon/Markus, Em Mon, 29 Aug 2016 16:12:39 +0200 Markus Heiserescreveu: > Am 29.08.2016 um 15:13 schrieb Mauro Carvalho Chehab > : > > > A macro definition is mapped via .. c:function:: at the > > ReST markup when using the following kernel-doc tag: > > > > /** > > * DMX_FE_ENTRY - Casts elements in the list of registered > > * front-ends from the generic type struct list_head > > * to the type * struct dmx_frontend > > * > > * @list: list of struct dmx_frontend > > */ > > #define DMX_FE_ENTRY(list) \ > > list_entry(list, struct dmx_frontend, connectivity_list) > > > > However, unlike a function description, the arguments of a macro > > doesn't contain the data type. > > > > This causes warnings when enabling Sphinx on nitkpick mode, > > like this one: > > ./drivers/media/dvb-core/demux.h:358: WARNING: c:type reference target > > not found: list > > I think this is a drawback of sphinx's C-domain, using function > definition for macros also. From the function documentation > > """This is also used to describe function-like preprocessor > macros. The names of the arguments should be given so > they may be used in the description.""" > > I think about to fix the nitpick message for macros (aka function > directive) in the C-domain extension (we already have). > > But for this, I need a rule to distinguish between macros > and functions ... is the uppercase of the macro name a good > rule to suppress the nitpick message? Any other suggestions? What's the status of the C domain patches meant to fix this issue? I managed to fix most warnings on media documents on nitpick mode. With this patch applied, there are only 21 warnings (and all are due to the lack of function or struct documentation). I'm about to patchbomb such fixup series. Yet, without this patch, and latest docs-next, there are 20 extra bogus warnings, due to function parameters: ./drivers/media/dvb-core/dvb_ringbuffer.h:121: WARNING: c:type reference target not found: rbuf ./drivers/media/dvb-core/dvb_ringbuffer.h:121: WARNING: c:type reference target not found: offs ./drivers/media/dvb-core/dvb_ringbuffer.h:130: WARNING: c:type reference target not found: rbuf ./drivers/media/dvb-core/dvb_ringbuffer.h:130: WARNING: c:type reference target not found: num ./drivers/media/dvb-core/dvb_ringbuffer.h:173: WARNING: c:type reference target not found: rbuf ./drivers/media/dvb-core/dvb_ringbuffer.h:173: WARNING: c:type reference target not found: byte ./drivers/media/dvb-core/demux.h:358: WARNING: c:type reference target not found: list ./include/media/media-device.h:263: WARNING: c:type reference target not found: mdev ./include/media/media-device.h:495: WARNING: c:type reference target not found: mdev ./include/media/media-device.h:495: WARNING: c:type reference target not found: udev ./include/media/media-device.h:495: WARNING: c:type reference target not found: name ./include/media/media-entity.h:527: WARNING: c:type reference target not found: gobj ./include/media/media-entity.h:536: WARNING: c:type reference target not found: gobj ./include/media/media-entity.h:545: WARNING: c:type reference target not found: gobj ./include/media/media-entity.h:554: WARNING: c:type reference target not found: gobj ./include/media/media-entity.h:563: WARNING: c:type reference target not found: intf ./include/media/media-entity.h:1041: WARNING: c:type reference target not found: entity ./include/media/media-entity.h:1041: WARNING: c:type reference target not found: operation ./include/media/v4l2-ctrls.h:397: WARNING: c:type reference target not found: hdl ./include/media/v4l2-ctrls.h:397: WARNING: c:type reference target not found: nr_of_controls_hint So, it would be great if we could either merge this patch or the ones that Markus did (assuming they're ready for merge). Regards, Mauro > > -- Markus -- > > > > > That happens because kernel-doc output for the above is: > > > > .. c:function:: DMX_FE_ENTRY ( list) > > > >Casts elements in the list of registered front-ends from the generic > > type struct list_head to the type * struct dmx_frontend > > > > **Parameters** > > > > ``list`` > > list of struct dmx_frontend > > > > As the type is blank, Sphinx would think that ``list`` is a type, > > and will try to add a cross reference for it, using their internal > > representation for c:type:`list`. > > > > However, ``list`` is not a type. So, that would cause either the > > above warning, or if a ``list`` type exists, it would create > > a reference to the wrong place at the doc. > > > > To avoid that, let's ommit macro arguments from c:function:: > > declaration. As each argument will appear below the Parameters, > > the type of the argument can be described there, if needed. > > > > Signed-off-by: Mauro Carvalho Chehab
Re: [PATCH v3] docs-rst: ignore arguments on macro definitions
Am 31.08.2016 um 12:26 schrieb Mauro Carvalho Chehab: > Em Wed, 31 Aug 2016 12:09:39 +0200 > Markus Heiser escreveu: > >> Am 31.08.2016 um 11:02 schrieb Jani Nikula : >> >>> On Wed, 31 Aug 2016, Markus Heiser wrote: I haven't tested your suggestion, but since *void* is in the list of stop-words: # These C types aren't described anywhere, so don't try to create # a cross-reference to them stopwords = set(( 'const', 'void', 'char', 'wchar_t', 'int', 'short', 'long', 'float', 'double', 'unsigned', 'signed', 'FILE', 'clock_t', 'time_t', 'ptrdiff_t', 'size_t', 'ssize_t', 'struct', '_Bool', )) I think it will work in the matter you think. However I like to prefer to fix it in the C-domain, using Mauro's suggestion on argument parsing. IMHO it is not the best solution to add a void type to the reST signature of a macro. This will result in a unusual output and does not fix what is wrong in Sphinx's c-domain (there is also a drawback in the index, where a function-type macro is referred as function, not as macro). >>> >>> From an API user's perspective, functions and function-like macros >>> should work interchangeably. >> >> Ah, OK. >> >>> Personally, I don't think there needs to be >>> a difference in the index. This seems to be the approach taken in >>> Sphinx, but it just doesn't work well for automatic documentation >>> generation because we can't deduce the parameter types from the macro >>> definition. >> >> In the index, sphinx refers only object-like macros with an entry >> "FOO (C macro))". Function-like macros are referred as "BAR (C function)". >> >> I thought it is more straight forward to refer all macros with a >> "BAR (C macro)" entry in the index. I will split this change in >> a separate patch, so we can decide if we like to patch the index >> that way. >> >> But now, as we discuss this, I have another doubt to fix the index. >> It might be confusing when writing references to those macros. >> >> Since function-like macros internally are functions in the c-domain, >> they are referred with ":c:func:`BAR`". On the other side, object-like >> macros are referred by role ":c:macro:`FOO`". >> >> Taking this into account, it might be one reason more to follow >> your conclusion that functions and function-like macros are >> interchangeable from the user's perspective. > > It is not uncommon to "promote" some such macros to inline > functions, in order to have a stronger type check, or to do the > reverse, when we need a more generic declaration that would work > for multiple types. > > So, keeping both macro function-like functions and functions using > the :c:function: seems to be the best, IMHO. It also makes life > easier for kernel-doc script. May, I was unclear. I don't want to change the behavior: """keeping both macro function-like functions and functions using the :c:function:""". The only thing I thought to change is, how the index entry will be. First I thought it might be more straight forward to refer func-like as "BAR (C macro)". But after Jani's conclusion, I had a doubt if this is really a better entry in the index, than that what sphinx already does "BAR (C function)". Sorry for the confusion. -- Markus -- -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v3] docs-rst: ignore arguments on macro definitions
Em Wed, 31 Aug 2016 12:09:39 +0200 Markus Heiserescreveu: > Am 31.08.2016 um 11:02 schrieb Jani Nikula : > > > On Wed, 31 Aug 2016, Markus Heiser wrote: > >> I haven't tested your suggestion, but since *void* is in the list > >> of stop-words: > >> > >># These C types aren't described anywhere, so don't try to create > >># a cross-reference to them > >>stopwords = set(( > >>'const', 'void', 'char', 'wchar_t', 'int', 'short', > >>'long', 'float', 'double', 'unsigned', 'signed', 'FILE', > >>'clock_t', 'time_t', 'ptrdiff_t', 'size_t', 'ssize_t', > >>'struct', '_Bool', > >>)) > >> > >> I think it will work in the matter you think. > >> > >> However I like to prefer to fix it in the C-domain, using > >> Mauro's suggestion on argument parsing. IMHO it is not > >> the best solution to add a void type to the reST signature > >> of a macro. This will result in a unusual output and does > >> not fix what is wrong in Sphinx's c-domain (there is also > >> a drawback in the index, where a function-type macro is > >> referred as function, not as macro). > > > > From an API user's perspective, functions and function-like macros > > should work interchangeably. > > Ah, OK. > > > Personally, I don't think there needs to be > > a difference in the index. This seems to be the approach taken in > > Sphinx, but it just doesn't work well for automatic documentation > > generation because we can't deduce the parameter types from the macro > > definition. > > In the index, sphinx refers only object-like macros with an entry > "FOO (C macro))". Function-like macros are referred as "BAR (C function)". > > I thought it is more straight forward to refer all macros with a > "BAR (C macro)" entry in the index. I will split this change in > a separate patch, so we can decide if we like to patch the index > that way. > > But now, as we discuss this, I have another doubt to fix the index. > It might be confusing when writing references to those macros. > > Since function-like macros internally are functions in the c-domain, > they are referred with ":c:func:`BAR`". On the other side, object-like > macros are referred by role ":c:macro:`FOO`". > > Taking this into account, it might be one reason more to follow > your conclusion that functions and function-like macros are > interchangeable from the user's perspective. It is not uncommon to "promote" some such macros to inline functions, in order to have a stronger type check, or to do the reverse, when we need a more generic declaration that would work for multiple types. So, keeping both macro function-like functions and functions using the :c:function: seems to be the best, IMHO. It also makes life easier for kernel-doc script. > > -- Markus -- > > > > > BR, > > Jani. > > > > > > -- > > Jani Nikula, Intel Open Source Technology Center > > -- > > To unsubscribe from this list: send the line "unsubscribe linux-doc" in > > the body of a message to majord...@vger.kernel.org > > More majordomo info at http://vger.kernel.org/majordomo-info.html > Thanks, Mauro -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v3] docs-rst: ignore arguments on macro definitions
Am 31.08.2016 um 11:02 schrieb Jani Nikula: > On Wed, 31 Aug 2016, Markus Heiser wrote: >> I haven't tested your suggestion, but since *void* is in the list >> of stop-words: >> >># These C types aren't described anywhere, so don't try to create >># a cross-reference to them >>stopwords = set(( >>'const', 'void', 'char', 'wchar_t', 'int', 'short', >>'long', 'float', 'double', 'unsigned', 'signed', 'FILE', >>'clock_t', 'time_t', 'ptrdiff_t', 'size_t', 'ssize_t', >>'struct', '_Bool', >>)) >> >> I think it will work in the matter you think. >> >> However I like to prefer to fix it in the C-domain, using >> Mauro's suggestion on argument parsing. IMHO it is not >> the best solution to add a void type to the reST signature >> of a macro. This will result in a unusual output and does >> not fix what is wrong in Sphinx's c-domain (there is also >> a drawback in the index, where a function-type macro is >> referred as function, not as macro). > > From an API user's perspective, functions and function-like macros > should work interchangeably. Ah, OK. > Personally, I don't think there needs to be > a difference in the index. This seems to be the approach taken in > Sphinx, but it just doesn't work well for automatic documentation > generation because we can't deduce the parameter types from the macro > definition. In the index, sphinx refers only object-like macros with an entry "FOO (C macro))". Function-like macros are referred as "BAR (C function)". I thought it is more straight forward to refer all macros with a "BAR (C macro)" entry in the index. I will split this change in a separate patch, so we can decide if we like to patch the index that way. But now, as we discuss this, I have another doubt to fix the index. It might be confusing when writing references to those macros. Since function-like macros internally are functions in the c-domain, they are referred with ":c:func:`BAR`". On the other side, object-like macros are referred by role ":c:macro:`FOO`". Taking this into account, it might be one reason more to follow your conclusion that functions and function-like macros are interchangeable from the user's perspective. -- Markus -- > > BR, > Jani. > > > -- > Jani Nikula, Intel Open Source Technology Center > -- > To unsubscribe from this list: send the line "unsubscribe linux-doc" in > the body of a message to majord...@vger.kernel.org > More majordomo info at http://vger.kernel.org/majordomo-info.html -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v3] docs-rst: ignore arguments on macro definitions
On Wed, 31 Aug 2016, Markus Heiserwrote: > I haven't tested your suggestion, but since *void* is in the list > of stop-words: > > # These C types aren't described anywhere, so don't try to create > # a cross-reference to them > stopwords = set(( > 'const', 'void', 'char', 'wchar_t', 'int', 'short', > 'long', 'float', 'double', 'unsigned', 'signed', 'FILE', > 'clock_t', 'time_t', 'ptrdiff_t', 'size_t', 'ssize_t', > 'struct', '_Bool', > )) > > I think it will work in the matter you think. > > However I like to prefer to fix it in the C-domain, using > Mauro's suggestion on argument parsing. IMHO it is not > the best solution to add a void type to the reST signature > of a macro. This will result in a unusual output and does > not fix what is wrong in Sphinx's c-domain (there is also > a drawback in the index, where a function-type macro is > referred as function, not as macro). >From an API user's perspective, functions and function-like macros should work interchangeably. Personally, I don't think there needs to be a difference in the index. This seems to be the approach taken in Sphinx, but it just doesn't work well for automatic documentation generation because we can't deduce the parameter types from the macro definition. BR, Jani. -- Jani Nikula, Intel Open Source Technology Center -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v3] docs-rst: ignore arguments on macro definitions
Am 29.08.2016 um 17:36 schrieb Jani Nikula: > On Mon, 29 Aug 2016, Mauro Carvalho Chehab wrote: >> Em Mon, 29 Aug 2016 16:12:39 +0200 >> Markus Heiser escreveu: >> >>> Am 29.08.2016 um 15:13 schrieb Mauro Carvalho Chehab >>> : >>> A macro definition is mapped via .. c:function:: at the ReST markup when using the following kernel-doc tag: /** * DMX_FE_ENTRY - Casts elements in the list of registered * front-ends from the generic type struct list_head * to the type * struct dmx_frontend * * @list: list of struct dmx_frontend */ #define DMX_FE_ENTRY(list) \ list_entry(list, struct dmx_frontend, connectivity_list) However, unlike a function description, the arguments of a macro doesn't contain the data type. This causes warnings when enabling Sphinx on nitkpick mode, like this one: ./drivers/media/dvb-core/demux.h:358: WARNING: c:type reference target not found: list >>> >>> I think this is a drawback of sphinx's C-domain, using function >>> definition for macros also. From the function documentation >>> >>> """This is also used to describe function-like preprocessor >>>macros. The names of the arguments should be given so >>>they may be used in the description.""" >>> >>> I think about to fix the nitpick message for macros (aka function >>> directive) in the C-domain extension (we already have). >> >> Yeah, that could produce a better output, if it is doable. >> >>> >>> But for this, I need a rule to distinguish between macros >>> and functions ... is the uppercase of the macro name a good >>> rule to suppress the nitpick message? >> >> No. There are lots of macros in lowercase. never did any stats about >> that, but I guess that we actually have a way more such macros in >> lowercase. >> >>> Any other suggestions? >> >> I guess the best thing is to check if the type is empty, just like >> on this patch. Macros are always: >> foo(arg1, arg2, arg3, ...) Yes, it is so clear, ... I'am a gawk ;-) >> while functions always have some type (with could be as complex as >> a function pointer). So, if all arguments match this rejex: >> \s*\S+\s* >> Then, it is a macro. Otherwise, it is a function. >> >> There's no way for the C domain to distinguish between a macro or >> a function when the number of arguments is zero, but, on such case, >> it doesn't really matter. > > What does Sphinx say if you add "void" as the type? Or a fake > "macroparam" type? Hi Jani, sorry for my late reply, I haven't tested your suggestion, but since *void* is in the list of stop-words: # These C types aren't described anywhere, so don't try to create # a cross-reference to them stopwords = set(( 'const', 'void', 'char', 'wchar_t', 'int', 'short', 'long', 'float', 'double', 'unsigned', 'signed', 'FILE', 'clock_t', 'time_t', 'ptrdiff_t', 'size_t', 'ssize_t', 'struct', '_Bool', )) I think it will work in the matter you think. However I like to prefer to fix it in the C-domain, using Mauro's suggestion on argument parsing. IMHO it is not the best solution to add a void type to the reST signature of a macro. This will result in a unusual output and does not fix what is wrong in Sphinx's c-domain (there is also a drawback in the index, where a function-type macro is referred as function, not as macro). I will give it a try, to eliminate these drawbacks in the C-domain and send a patch series, we can discuss further. -- Markus -- > > If those hacks don't help, Mauro's suggestion seems sane. > > BR, > Jani. > > > >> >> Thanks, >> Mauro >> -- >> To unsubscribe from this list: send the line "unsubscribe linux-doc" in >> the body of a message to majord...@vger.kernel.org >> More majordomo info at http://vger.kernel.org/majordomo-info.html > > -- > Jani Nikula, Intel Open Source Technology Center -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v3] docs-rst: ignore arguments on macro definitions
On Mon, 29 Aug 2016, Mauro Carvalho Chehabwrote: > Em Mon, 29 Aug 2016 16:12:39 +0200 > Markus Heiser escreveu: > >> Am 29.08.2016 um 15:13 schrieb Mauro Carvalho Chehab >> : >> >> > A macro definition is mapped via .. c:function:: at the >> > ReST markup when using the following kernel-doc tag: >> > >> >/** >> > * DMX_FE_ENTRY - Casts elements in the list of registered >> > * front-ends from the generic type struct list_head >> > * to the type * struct dmx_frontend >> > * >> > * @list: list of struct dmx_frontend >> > */ >> > #define DMX_FE_ENTRY(list) \ >> >list_entry(list, struct dmx_frontend, connectivity_list) >> > >> > However, unlike a function description, the arguments of a macro >> > doesn't contain the data type. >> > >> > This causes warnings when enabling Sphinx on nitkpick mode, >> > like this one: >> >./drivers/media/dvb-core/demux.h:358: WARNING: c:type reference target >> > not found: list >> >> I think this is a drawback of sphinx's C-domain, using function >> definition for macros also. From the function documentation >> >> """This is also used to describe function-like preprocessor >> macros. The names of the arguments should be given so >> they may be used in the description.""" >> >> I think about to fix the nitpick message for macros (aka function >> directive) in the C-domain extension (we already have). > > Yeah, that could produce a better output, if it is doable. > >> >> But for this, I need a rule to distinguish between macros >> and functions ... is the uppercase of the macro name a good >> rule to suppress the nitpick message? > > No. There are lots of macros in lowercase. never did any stats about > that, but I guess that we actually have a way more such macros in > lowercase. > >> Any other suggestions? > > I guess the best thing is to check if the type is empty, just like > on this patch. Macros are always: > foo(arg1, arg2, arg3, ...) > > while functions always have some type (with could be as complex as > a function pointer). So, if all arguments match this rejex: > \s*\S+\s* > Then, it is a macro. Otherwise, it is a function. > > There's no way for the C domain to distinguish between a macro or > a function when the number of arguments is zero, but, on such case, > it doesn't really matter. What does Sphinx say if you add "void" as the type? Or a fake "macroparam" type? If those hacks don't help, Mauro's suggestion seems sane. BR, Jani. > > Thanks, > Mauro > -- > To unsubscribe from this list: send the line "unsubscribe linux-doc" in > the body of a message to majord...@vger.kernel.org > More majordomo info at http://vger.kernel.org/majordomo-info.html -- Jani Nikula, Intel Open Source Technology Center -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v3] docs-rst: ignore arguments on macro definitions
Em Mon, 29 Aug 2016 16:12:39 +0200 Markus Heiserescreveu: > Am 29.08.2016 um 15:13 schrieb Mauro Carvalho Chehab > : > > > A macro definition is mapped via .. c:function:: at the > > ReST markup when using the following kernel-doc tag: > > > > /** > > * DMX_FE_ENTRY - Casts elements in the list of registered > > * front-ends from the generic type struct list_head > > * to the type * struct dmx_frontend > > * > > * @list: list of struct dmx_frontend > > */ > > #define DMX_FE_ENTRY(list) \ > > list_entry(list, struct dmx_frontend, connectivity_list) > > > > However, unlike a function description, the arguments of a macro > > doesn't contain the data type. > > > > This causes warnings when enabling Sphinx on nitkpick mode, > > like this one: > > ./drivers/media/dvb-core/demux.h:358: WARNING: c:type reference target > > not found: list > > I think this is a drawback of sphinx's C-domain, using function > definition for macros also. From the function documentation > > """This is also used to describe function-like preprocessor > macros. The names of the arguments should be given so > they may be used in the description.""" > > I think about to fix the nitpick message for macros (aka function > directive) in the C-domain extension (we already have). Yeah, that could produce a better output, if it is doable. > > But for this, I need a rule to distinguish between macros > and functions ... is the uppercase of the macro name a good > rule to suppress the nitpick message? No. There are lots of macros in lowercase. never did any stats about that, but I guess that we actually have a way more such macros in lowercase. > Any other suggestions? I guess the best thing is to check if the type is empty, just like on this patch. Macros are always: foo(arg1, arg2, arg3, ...) while functions always have some type (with could be as complex as a function pointer). So, if all arguments match this rejex: \s*\S+\s* Then, it is a macro. Otherwise, it is a function. There's no way for the C domain to distinguish between a macro or a function when the number of arguments is zero, but, on such case, it doesn't really matter. Thanks, Mauro -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v3] docs-rst: ignore arguments on macro definitions
Am 29.08.2016 um 15:13 schrieb Mauro Carvalho Chehab: > A macro definition is mapped via .. c:function:: at the > ReST markup when using the following kernel-doc tag: > > /** >* DMX_FE_ENTRY - Casts elements in the list of registered >* front-ends from the generic type struct list_head >* to the type * struct dmx_frontend >* >* @list: list of struct dmx_frontend >*/ >#define DMX_FE_ENTRY(list) \ > list_entry(list, struct dmx_frontend, connectivity_list) > > However, unlike a function description, the arguments of a macro > doesn't contain the data type. > > This causes warnings when enabling Sphinx on nitkpick mode, > like this one: > ./drivers/media/dvb-core/demux.h:358: WARNING: c:type reference target > not found: list I think this is a drawback of sphinx's C-domain, using function definition for macros also. From the function documentation """This is also used to describe function-like preprocessor macros. The names of the arguments should be given so they may be used in the description.""" I think about to fix the nitpick message for macros (aka function directive) in the C-domain extension (we already have). But for this, I need a rule to distinguish between macros and functions ... is the uppercase of the macro name a good rule to suppress the nitpick message? Any other suggestions? -- Markus -- > > That happens because kernel-doc output for the above is: > > .. c:function:: DMX_FE_ENTRY ( list) > > Casts elements in the list of registered front-ends from the generic > type struct list_head to the type * struct dmx_frontend > > **Parameters** > > ``list`` > list of struct dmx_frontend > > As the type is blank, Sphinx would think that ``list`` is a type, > and will try to add a cross reference for it, using their internal > representation for c:type:`list`. > > However, ``list`` is not a type. So, that would cause either the > above warning, or if a ``list`` type exists, it would create > a reference to the wrong place at the doc. > > To avoid that, let's ommit macro arguments from c:function:: > declaration. As each argument will appear below the Parameters, > the type of the argument can be described there, if needed. > > Signed-off-by: Mauro Carvalho Chehab > --- > > v3: version 2 patch caused a regression when handling function arguments, > because the counter were not incremented on all cases. Fix it. > > scripts/kernel-doc | 5 +++-- > 1 file changed, 3 insertions(+), 2 deletions(-) > > diff --git a/scripts/kernel-doc b/scripts/kernel-doc > index d225e178aa1b..bac0af4fc659 100755 > --- a/scripts/kernel-doc > +++ b/scripts/kernel-doc > @@ -1846,14 +1846,15 @@ sub output_function_rst(%) { > if ($count ne 0) { > print ", "; > } > - $count++; > $type = $args{'parametertypes'}{$parameter}; > > if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { > # pointer-to-function > print $1 . $parameter . ") (" . $2; > - } else { > + $count++; > + } elsif ($type ne "") { > print $type . " " . $parameter; > + $count++; > } >} >print ")\n\n"; > -- > 2.7.4 > > > -- > To unsubscribe from this list: send the line "unsubscribe linux-media" in > the body of a message to majord...@vger.kernel.org > More majordomo info at http://vger.kernel.org/majordomo-info.html -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH v3] docs-rst: ignore arguments on macro definitions
A macro definition is mapped via .. c:function:: at the ReST markup when using the following kernel-doc tag: /** * DMX_FE_ENTRY - Casts elements in the list of registered * front-ends from the generic type struct list_head * to the type * struct dmx_frontend * * @list: list of struct dmx_frontend */ #define DMX_FE_ENTRY(list) \ list_entry(list, struct dmx_frontend, connectivity_list) However, unlike a function description, the arguments of a macro doesn't contain the data type. This causes warnings when enabling Sphinx on nitkpick mode, like this one: ./drivers/media/dvb-core/demux.h:358: WARNING: c:type reference target not found: list That happens because kernel-doc output for the above is: .. c:function:: DMX_FE_ENTRY ( list) Casts elements in the list of registered front-ends from the generic type struct list_head to the type * struct dmx_frontend **Parameters** ``list`` list of struct dmx_frontend As the type is blank, Sphinx would think that ``list`` is a type, and will try to add a cross reference for it, using their internal representation for c:type:`list`. However, ``list`` is not a type. So, that would cause either the above warning, or if a ``list`` type exists, it would create a reference to the wrong place at the doc. To avoid that, let's ommit macro arguments from c:function:: declaration. As each argument will appear below the Parameters, the type of the argument can be described there, if needed. Signed-off-by: Mauro Carvalho Chehab--- v3: version 2 patch caused a regression when handling function arguments, because the counter were not incremented on all cases. Fix it. scripts/kernel-doc | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/scripts/kernel-doc b/scripts/kernel-doc index d225e178aa1b..bac0af4fc659 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1846,14 +1846,15 @@ sub output_function_rst(%) { if ($count ne 0) { print ", "; } - $count++; $type = $args{'parametertypes'}{$parameter}; if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { # pointer-to-function print $1 . $parameter . ") (" . $2; - } else { + $count++; + } elsif ($type ne "") { print $type . " " . $parameter; + $count++; } } print ")\n\n"; -- 2.7.4 -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html