1. 15 Oct, 2020 40 commits
    • Mauro Carvalho Chehab's avatar
      docs: libata.rst: fix a wrong usage of :c:type: tag · b989451b
      Mauro Carvalho Chehab authored
      The usage of :c:type: to reference to a struct member is wrong,
      as pointed by Sphinx 3:
      
      	./Documentation/driver-api/libata.rst:511: WARNING: Unparseable C cross-reference: 'qc->complete_fn'
      	Invalid C declaration: Expected end of definition. [error at 2]
      	  qc->complete_fn
      	  --^
      
      Instead, let's use :c:expr: for such purpose.
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      b989451b
    • Mauro Carvalho Chehab's avatar
      docs: kgdb.rst: fix :c:type: usages · 365ff56f
      Mauro Carvalho Chehab authored
      Which Sphinx 3, :c:type:  can't be used anymore for structs,
      as this should be used only for typedefs.
      
      Rely on automarkup.py for struct references.
      
      This file has an special case, though: it uses the tag also
      to point to an array. Let's use, instead, :c:expr: for such
      purpose, as it should do the right thing.
      
      This should fix this warning:
      
      	./Documentation/dev-tools/kgdb.rst:875: WARNING: Unparseable C cross-reference: 'kdb_poll_funcs[]'
      	Invalid C declaration: Expected end of definition. [error at 14]
      	  kdb_poll_funcs[]
      	  --------------^
      Acked-by: default avatarDaniel Thompson <daniel.thompson@linaro.org>
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      365ff56f
    • Mauro Carvalho Chehab's avatar
      docs: fpga: replace :c:member: macros · 64d41516
      Mauro Carvalho Chehab authored
      Those macros are not doing the right thing with Sphinx 3,
      causing parse errors:
      
      	./Documentation/driver-api/fpga/fpga-mgr.rst:104: WARNING: Unparseable C cross-reference: 'fpga_manager->state'
      	Invalid C declaration: Expected end of definition. [error at 12]
      	  fpga_manager->state
      	  ------------^
      	./Documentation/driver-api/fpga/fpga-programming.rst:18: WARNING: Unparseable C cross-reference: 'fpga_region->info'
      	Invalid C declaration: Expected end of definition. [error at 11]
      	  fpga_region->info
      	  -----------^
      	./Documentation/driver-api/fpga/fpga-region.rst:62: WARNING: Unparseable C cross-reference: 'fpga_region->bridge_list'
      	Invalid C declaration: Expected end of definition. [error at 11]
      	  fpga_region->bridge_list
      	  -----------^
      	./Documentation/driver-api/fpga/fpga-region.rst:62: WARNING: Unparseable C cross-reference: 'fpga_region->get_bridges'
      	Invalid C declaration: Expected end of definition. [error at 11]
      	  fpga_region->get_bridges
      	  -----------^
      
      Replace them by :c:expr:, with does what's desired.
      Reviewed-by: default avatarMoritz Fischer <mdf@kernel.org>
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      64d41516
    • Mauro Carvalho Chehab's avatar
      docs: writing-an-alsa-driver.rst: fix some bad c:func: markups · 4d9d18ad
      Mauro Carvalho Chehab authored
      Some such markups are invalid, as reported by Sphinx:
      
      	./Documentation/sound/kernel-api/writing-an-alsa-driver.rst:3317: WARNING: Unparseable C cross-reference: 'snd_rawmidi_transmit*'
      	Invalid C declaration: Expected end of definition. [error at 20]
      	  snd_rawmidi_transmit*
      	  --------------------^
      	./Documentation/sound/kernel-api/writing-an-alsa-driver.rst:3917: WARNING: Unparseable C cross-reference: 'copy_from/to_user'
      	Invalid C declaration: Expected end of definition. [error at 9]
      	  copy_from/to_user
      	  ---------^
      
      The first case seems to be better replaced by a literal.
      
      For the second one, let's generate cross-references, by
      spliting it in two.
      Reviewed-by: default avatarTakashi Iwai <tiwai@suse.de>
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      4d9d18ad
    • Mauro Carvalho Chehab's avatar
      docs: block: blk-mq.rst: get rid of :c:type · 8ac86734
      Mauro Carvalho Chehab authored
      The :c:type macros are not used properly there, as reported
      by Sphinx 3:
      
      	./Documentation/block/blk-mq.rst:112: WARNING: Unparseable C cross-reference: 'hctx->dispatch'
      	Invalid C declaration: Expected end of definition. [error at 4]
      	  hctx->dispatch
      	  ----^
      
      Also, they won't be generating any cross references.
      
      So, replace them by a literal markup.
      Reviewed-by: default avatarAndré Almeida <andrealmeid@collabora.com>
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      8ac86734
    • Mauro Carvalho Chehab's avatar
      docs: sound: writing-an-alsa-driver.rst: get rid of :c:type · 68735902
      Mauro Carvalho Chehab authored
      the :c:type shouldn't be used with structs with Sphinx 3,
      as the C domain there uses .. c:struct for structs.
      
      As we have the automarkup extension, let's just get rid of
      all :c:type as a whole, as those will be automagically
      marked as such.
      
      This solves a bunch of warnings with Sphinx 3, like those:
      
      	.../Documentation/sound/kernel-api/writing-an-alsa-driver.rst:490: WARNING: Unparseable C cross-reference: 'calling snd_card_free'
      	Invalid C declaration: Expected end of definition. [error at 8]
      	  calling snd_card_free
      	  --------^
      	.../Documentation/sound/kernel-api/writing-an-alsa-driver.rst:3328: WARNING: Unparseable C cross-reference: 'snd_rawmidi_transmit*'
      	Invalid C declaration: Expected end of definition. [error at 20]
      	  snd_rawmidi_transmit*
      	  --------------------^
      	.../Documentation/sound/kernel-api/writing-an-alsa-driver.rst:3928: WARNING: Unparseable C cross-reference: 'copy_from/to_user'
      	Invalid C declaration: Expected end of definition. [error at 9]
      	  copy_from/to_user
      	  ---------^
      Reviewed-by: default avatarTakashi Iwai <tiwai@suse.de>
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      68735902
    • Mauro Carvalho Chehab's avatar
      docs: devices.rst: get rid of :c:type macros · 6624d64d
      Mauro Carvalho Chehab authored
      There's no need to use macros to use :c:type on this file,
      as automarkup.py should do this automatically.
      
      Also, this breaks compatibility with Sphinx 3.x, as there,
      structs should be declared using .. c:struct.
      
      So, get rid of them.
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      6624d64d
    • Mauro Carvalho Chehab's avatar
      docs: fs: fscrypt.rst: get rid of :c:type: tags · 74e2f8d3
      Mauro Carvalho Chehab authored
      The :c:type: tag has problems with Sphinx 3.x, as structs
      there should be declared with c:struct.
      
      So, remove them, relying at automarkup.py extension to
      convert them into cross-references.
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      74e2f8d3
    • Mauro Carvalho Chehab's avatar
      docs: pstore-blk.rst: fix kernel-doc tags · b30fd8e9
      Mauro Carvalho Chehab authored
      There is currently a problem with kernel-doc tags from blk.c:
      
      	.../Documentation/admin-guide/pstore-blk:239: ./fs/pstore/blk.c:175: WARNING: Duplicate C declaration, also defined in 'admin-guide/pstore-blk'.
      	Declaration is 'register_pstore_device'.
      	.../Documentation/admin-guide/pstore-blk:239: ./fs/pstore/blk.c:432: WARNING: Duplicate C declaration, also defined in 'admin-guide/pstore-blk'.
      	Declaration is 'register_pstore_blk'.
      	.../Documentation/admin-guide/pstore-blk:242: ./include/linux/pstore_blk.h:43: WARNING: Duplicate C declaration, also defined in 'admin-guide/pstore-blk'.
      	Declaration is 'pstore_device_info'.
      
      Basically, the internal parts is shown with :export:, instead
      of :internal:. Yet, there are some other exported docs that
      aren't at the document, because they lack :identifiers:.
      
      So, instead, let's just use :export: at the kAPI part of
      the documentation.
      Acked-by: default avatarKees Cook <keescook@chromium.org>
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      b30fd8e9
    • Mauro Carvalho Chehab's avatar
      docs: basics.rst: get rid of rcu kernel-doc macros · 044248db
      Mauro Carvalho Chehab authored
      Those are already defined at kernel-api.rst, as part of the
      synchronization primitives chapter.
      
      This solves several Sphinx 3 warnings, like:
      
      	.../Documentation/driver-api/basics.rst: WARNING: Duplicate C declaration, also defined in 'core-api/kernel-api'.
      	Declaration is 'rcu_idle_enter'.
      	.../Documentation/driver-api/basics.rst: WARNING: Duplicate C declaration, also defined in 'core-api/kernel-api'.
      	Declaration is 'rcu_idle_exit'.
      	.../Documentation/driver-api/basics.rst: WARNING: Duplicate C declaration, also defined in 'core-api/kernel-api'.
      	Declaration is 'rcu_is_watching'.
      	.../Documentation/driver-api/basics.rst: WARNING: Duplicate C declaration, also defined in 'core-api/kernel-api'.
      	Declaration is 'call_rcu'.
      	.../Documentation/driver-api/basics.rst: WARNING: Duplicate C declaration, also defined in 'core-api/kernel-api'.
      	Declaration is 'synchronize_rcu'.
      	...
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      044248db
    • Mauro Carvalho Chehab's avatar
      docs: device_link.rst: remove duplicated kernel-doc include · 58bc57b0
      Mauro Carvalho Chehab authored
      The infrastructure.rst file already includes the external
      symbols from drivers/base/core.c.
      
      Duplicating 3 functions there causes namespace collisions:
      
      	Documentation/driver-api/device_link.rst: WARNING: Duplicate C declaration, also defined in 'driver-api/infrastructure'.
      	Declaration is 'device_link_state'.
      	Documentation/driver-api/device_link.rst: WARNING: Duplicate C declaration, also defined in 'driver-api/infrastructure'.
      	Declaration is 'device_link_add'.
      	Documentation/driver-api/device_link.rst: WARNING: Duplicate C declaration, also defined in 'driver-api/infrastructure'.
      	Declaration is 'device_link_del'.
      	Documentation/driver-api/device_link.rst: WARNING: Duplicate C declaration, also defined in 'driver-api/infrastructure'.
      	Declaration is 'device_link_remove'.
      
      So, drop the reference, adding just a mention to the functions
      associated with device_link.
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      58bc57b0
    • Mauro Carvalho Chehab's avatar
      docs: scsi: target.rst: remove iSCSI transport class kernel-doc markup · 3048ba60
      Mauro Carvalho Chehab authored
      This is already included at scsi.rst. So, remove the duplication,
      in order to avoid Sphinx warnings.
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      3048ba60
    • Mauro Carvalho Chehab's avatar
      docs: basics.rst: move kernel-doc workqueue markups to workqueue.rst · c9e3d519
      Mauro Carvalho Chehab authored
      As there's already a rst file with workqueue markups, containing
      part of them, move the other definitions, in order to avoid
      warnings with Sphinx.
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      c9e3d519
    • Mauro Carvalho Chehab's avatar
      docs: remove sound API duplication · 1842c96b
      Mauro Carvalho Chehab authored
      The sound API is documented on two different parts:
      under Documentation/driver-api/sound.rst and under
      Documentation/sound/kernel-api/alsa-driver-api.rst.
      
      The alsa-driver-api.rst seems more complete, and APIs
      are split per type. There's just one missing kernel-doc
      markup there.
      
      Add it and drop the duplicated one.
      Reviewed-by: default avatarTakashi Iwai <tiwai@suse.de>
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      1842c96b
    • Mauro Carvalho Chehab's avatar
      docs: kernel-api.rst: drop kernel/irq/manage.c kernel-doc tag · f182e7fd
      Mauro Carvalho Chehab authored
      This is already included at genericirq.rst. Adding it twice
      causes C namespace duplication:
      
      	.../Documentation/core-api/kernel-api:237: ../kernel/irq/manage.c:100: WARNING: Duplicate C declaration, also defined in 'genericirq'.
      	Declaration is 'synchronize_hardirq'.
      	.../Documentation/core-api/kernel-api:237: ../kernel/irq/manage.c:128: WARNING: Duplicate C declaration, also defined in 'genericirq'.
      	Declaration is 'synchronize_irq'.
      	.../Documentation/core-api/kernel-api:237: ../kernel/irq/manage.c:443: WARNING: Duplicate C declaration, also defined in 'genericirq'.
      	Declaration is 'irq_set_affinity_notifier'.
      	...
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      f182e7fd
    • Mauro Carvalho Chehab's avatar
      docs: genericirq.rst: don't document chip.c functions twice · 9b9b0bda
      Mauro Carvalho Chehab authored
      Currently, kernel/irq/chip.c is included twice, one for
      export functions, and then for internal ones. However, as
      the :export:  and :internal: tags are missing, they ended
      being included twice.
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      9b9b0bda
    • Mauro Carvalho Chehab's avatar
      docs: net: ieee802154.rst: fix C expressions · 640e3f80
      Mauro Carvalho Chehab authored
      There are some warnings produced with Sphinx 3.x:
      
      	Documentation/networking/ieee802154.rst:29: WARNING: Error in declarator or parameters
      	Invalid C declaration: Expecting "(" in parameters. [error at 7]
      	  int sd = socket(PF_IEEE802154, SOCK_DGRAM, 0);
      	  -------^
      	Documentation/networking/ieee802154.rst:134: WARNING: Invalid C declaration: Expected end of definition. [error at 81]
      	  void ieee802154_rx_irqsafe(struct ieee802154_hw *hw, struct sk_buff *skb, u8 lqi):
      	  ---------------------------------------------------------------------------------^
      	Documentation/networking/ieee802154.rst:139: WARNING: Invalid C declaration: Expected end of definition. [error at 95]
      	  void ieee802154_xmit_complete(struct ieee802154_hw *hw, struct sk_buff *skb, bool ifs_handling):
      	  -----------------------------------------------------------------------------------------------^
      	Documentation/networking/ieee802154.rst:158: WARNING: Invalid C declaration: Expected end of definition. [error at 35]
      	  int start(struct ieee802154_hw *hw):
      	  -----------------------------------^
      	Documentation/networking/ieee802154.rst:162: WARNING: Invalid C declaration: Expected end of definition. [error at 35]
      	  void stop(struct ieee802154_hw *hw):
      	  -----------------------------------^
      	Documentation/networking/ieee802154.rst:166: WARNING: Invalid C declaration: Expected end of definition. [error at 61]
      	  int xmit_async(struct ieee802154_hw *hw, struct sk_buff *skb):
      	  -------------------------------------------------------------^
      	Documentation/networking/ieee802154.rst:171: WARNING: Invalid C declaration: Expected end of definition. [error at 43]
      	  int ed(struct ieee802154_hw *hw, u8 *level):
      	  -------------------------------------------^
      	Documentation/networking/ieee802154.rst:176: WARNING: Invalid C declaration: Expected end of definition. [error at 62]
      	  int set_channel(struct ieee802154_hw *hw, u8 page, u8 channel):
      	  --------------------------------------------------------------^
      
      Caused by some bad c:function: prototypes. Fix them.
      Acked-by: default avatarDavid S. Miller <davem@davemloft.net>
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      640e3f80
    • Mauro Carvalho Chehab's avatar
      docs: it_IT: fix namespace collisions at locking.rst · 71a8156e
      Mauro Carvalho Chehab authored
      The C domain functions there collide with the English ones,
      due to namespace collision, generating lots of warnings with
      Sphinx 3.x:
      
      	./include/linux/mutex.h:121: WARNING: Duplicate C declaration, also defined in 'translations/it_IT/kernel-hacking/locking'.
      	Declaration is 'mutex_init'.
      	./include/linux/mutex.h:152: WARNING: Duplicate C declaration, also defined in 'translations/it_IT/kernel-hacking/locking'.
      	Declaration is 'mutex_is_locked'.
      	./include/linux/mutex.h:226: WARNING: Duplicate C declaration, also defined in 'translations/it_IT/kernel-hacking/locking'.
      	Declaration is 'mutex_trylock_recursive'.
      	./kernel/locking/mutex.c:281: WARNING: Duplicate C declaration, also defined in 'translations/it_IT/kernel-hacking/locking'.
      	Declaration is 'mutex_lock'.
      	...
      
      Add a namespace tag there, in order to prevent that.
      Acked-by: default avatarFederico Vaga <federico.vaga@vaga.pv.it>
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      71a8156e
    • Mauro Carvalho Chehab's avatar
      docs: trace-uses.rst: remove bogus c-domain tags · d7faad15
      Mauro Carvalho Chehab authored
      There are some c-domain tags that are wrong. While this won't
      cause problems with Sphinx < 3.0, this cause troubles with
      newer versions, as the C parser won't recognize the contents
      of the tag, and will drop it from the output.
      
      Let's just place them at literal blocks.
      Reviewed-by: default avatarKamalesh Babulal <kamalesh@linux.vnet.ibm.com>
      Acked-by: default avatarSteven Rostedt (VMware) <rostedt@goodmis.org>
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      d7faad15
    • Mauro Carvalho Chehab's avatar
      docs: get rid of :c:type explicit declarations for structs · 9303c9d5
      Mauro Carvalho Chehab authored
      The :c:type:`foo` only works properly with structs before
      Sphinx 3.x.
      
      On Sphinx 3.x, structs should now be declared using the
      .. c:struct, and referenced via :c:struct tag.
      
      As we now have the automarkup.py macro, that automatically
      convert:
      	struct foo
      
      into cross-references, let's get rid of that, solving
      several warnings when building docs with Sphinx 3.x.
      
      Reviewed-by: André Almeida <andrealmeid@collabora.com> # blk-mq.rst
      Reviewed-by: Takashi Iwai <tiwai@suse.de> # sound
      Reviewed-by: default avatarMike Rapoport <rppt@linux.ibm.com>
      Reviewed-by: default avatarGreg Kroah-Hartman <gregkh@linuxfoundation.org>
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      9303c9d5
    • Mauro Carvalho Chehab's avatar
      docs: remove some replace macros like |struct foo| · abc59fd4
      Mauro Carvalho Chehab authored
      There are three files with replace macros for structs,
      mapping them into Sphinx 2.x C domain references.
      
      Well, this is broken on Sphinx 3.x. Also, for Sphinx 2.x,
      the automarkup macro should be able to take care of them.
      
      So, let's just drop those.
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      abc59fd4
    • Mauro Carvalho Chehab's avatar
      media: cec-core.rst: don't use c:type for structs · 5b76632e
      Mauro Carvalho Chehab authored
      The new C domain code on Sphinx 3 doesn't allow anymore
      to use c:type:: for structs.
      
      Now that cdomain.py has backward support, let's use
      c:struct:: instead.
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      5b76632e
    • Mauro Carvalho Chehab's avatar
      media: docs: make RC documents more compatible with Sphinx 3.1+ · 5f536f4a
      Mauro Carvalho Chehab authored
      Sphinx 3.x broke support for the cdomain.py extension, as the
      c domain code was rewritten. Due to that, the c tags need to
      be re-written, in order to use the new c domain notation.
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      5f536f4a
    • Mauro Carvalho Chehab's avatar
      media: docs: make MC documents more compatible with Sphinx 3.1+ · 937e6805
      Mauro Carvalho Chehab authored
      Sphinx 3.x broke support for the cdomain.py extension, as the
      c domain code was rewritten. Due to that, the c tags need to
      be re-written, in order to use the new c domain notation.
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      937e6805
    • Mauro Carvalho Chehab's avatar
      media: docs: make DVB documents more compatible with Sphinx 3.1+ · f9b2e8aa
      Mauro Carvalho Chehab authored
      Sphinx 3.x broke support for the cdomain.py extension, as the
      c domain code was rewritten. Due to that, the c tags need to
      be re-written, in order to use the new c domain notation.
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      f9b2e8aa
    • Mauro Carvalho Chehab's avatar
      media: docs: make V4L documents more compatible with Sphinx 3.1+ · 407e84cd
      Mauro Carvalho Chehab authored
      Sphinx 3.x broke support for the cdomain.py extension, as the
      c domain code was rewritten. Due to that, the c tags need to
      be re-written, in order to use the new c domain notation.
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      407e84cd
    • Mauro Carvalho Chehab's avatar
      media: docs: make CEC documents compatible with Sphinx 3.1+ · 01fae02d
      Mauro Carvalho Chehab authored
      Sphinx 3.x broke support for the cdomain.py extension, as the
      c domain code was rewritten. Due to that, the c tags need to
      be re-written, in order to use the new c domain notation.
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      01fae02d
    • Nícolas F. R. A. Prado's avatar
      docs: automarkup.py: Add cross-reference for parametrized C macros · c51d9b04
      Nícolas F. R. A. Prado authored
      Sphinx 3 added support for declaring C macros with parameters using the
      :c:macro role.
      
      To support automarkup for both functions and parametrized macros using
      the same regex (words ending in ()), try to cross-reference to both, and
      only fall back to regular text if neither exist.
      Signed-off-by: default avatarNícolas F. R. A. Prado <nfraprado@protonmail.com>
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      c51d9b04
    • Nícolas F. R. A. Prado's avatar
      docs: automarkup.py: Skip C reserved words when cross-referencing · 3050edfd
      Nícolas F. R. A. Prado authored
      With the transition to Sphinx 3, new warnings were caused by
      automarkup, exposing bugs in the name matching.
      
      When automarkup parsed a text like "struct struct" in the documentation,
      it tried to cross-reference to a "struct" symbol, which is recognized as
      a C reserved word by Sphinx 3, generating a warning.
      
      Add some C reserved words (only the ones that were causing warnings) to
      a list and skip them while trying to cross-reference.
      Signed-off-by: default avatarNícolas F. R. A. Prado <nfraprado@protonmail.com>
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      3050edfd
    • Nícolas F. R. A. Prado's avatar
      docs: automarkup.py: Fix regexes to solve sphinx 3 warnings · f66e47f9
      Nícolas F. R. A. Prado authored
      With the transition to Sphinx 3, new warnings were generated by
      automarkup, exposing bugs in the regexes.
      
      The warnings were caused by the expressions matching words in the
      translated versions of the documentation, since any unicode character
      was matched.
      
      Fix the regular expression by making the C regexes use ASCII and
      ensuring the expressions only match the beginning of words,
      in order to avoid warnings like this:
      
      	WARNING: Unparseable C cross-reference: '调用debugfs_rename'
      
      That's probably due to the lack of using spaces between words
      on Chinese.
      Signed-off-by: default avatarNícolas F. R. A. Prado <nfraprado@protonmail.com>
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      f66e47f9
    • Nícolas F. R. A. Prado's avatar
      docs: automarkup.py: Use new C roles in Sphinx 3 · 06dc65b0
      Nícolas F. R. A. Prado authored
      While Sphinx 2 used a single c:type role for struct, union, enum and
      typedef, Sphinx 3 uses a specific role for each one.
      To keep backward compatibility, detect the Sphinx version and use the
      correct roles for that version.
      Signed-off-by: default avatarNícolas F. R. A. Prado <nfraprado@protonmail.com>
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      06dc65b0
    • Mauro Carvalho Chehab's avatar
      docs: kerneldoc.py: add support for kerneldoc -nosymbol · 2791f47d
      Mauro Carvalho Chehab authored
      Currently, there's no way to exclude identifiers from
      a kernel-doc markup. Add support for it.
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      2791f47d
    • Mauro Carvalho Chehab's avatar
      docs: kerneldoc.py: append the name of the parsed doc file · 91fc6d8a
      Mauro Carvalho Chehab authored
      Finding where an error like this was generated:
      	../lib/math/div64.c:73: WARNING: Duplicate C declaration, also defined in 'kernel-api'.
      
      Can take some time, as there's no glue about what kernel-doc
      tag generated it. It is a way better to display it as:
      
      	.../Documentation/core-api/kernel-api:171: ../lib/math/div64.c:73: WARNING: Duplicate C declaration, also defined in 'kernel-api'.
      	Declaration is 'div_s64_rem'.
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      91fc6d8a
    • Mauro Carvalho Chehab's avatar
      docs: cdomain.py: extend it to handle new Sphinx 3.x tags · 95f49490
      Mauro Carvalho Chehab authored
      While most of the C domain parsing is done via kernel-doc,
      some RST files use C domain tags directly.
      
      While several of them can be removed for Sphinx < 3.0, due
      to automarkup.py, and several others that could be
      converted into kernel-doc markups, changes like that are
      time-consuming, and may not fit all cases.
      
      As we already have the cdomain.py for handing backward
      compatibility with Sphinx versions below 3.0, let's
      make it more complete, in order to cover any usage of the
      newer tags outside kernel-doc.
      
      This way, it should be feasible to use the new tags inside
      the Kernel tree, without losing backward compatibility.
      
      This should allow fixing the remaining warnings with
      the Kernel tags.
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      95f49490
    • Mauro Carvalho Chehab's avatar
      docs: cdomain.py: add support for a new Sphinx 3.1+ tag · 71e552ae
      Mauro Carvalho Chehab authored
      Since Sphinx 3.0, the C domain code was rewritten, but only
      after version 3.1 it got support for setting namespaces on
      C domains, with is something that it is required, in order to
      document system calls, like ioctl() and others.
      
      As part of changing the documentation subsystem to properly
      build with Sphinx 3.1+, add support for such new tag:
      
      	.. c:namespace::"
      
      Such tag optionally replaces the optional "name" tag for functions,
      setting a single namespace domain for all C references found
      at the file.
      
      With that, it should be possible to convert existing
      documentation to be compatible with both Sphinx 1.x/2.x and
      3.1+.
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      71e552ae
    • Mauro Carvalho Chehab's avatar
      scripts: kernel-doc: try to use c:function if possible · 6e9e4158
      Mauro Carvalho Chehab authored
      There are a few namespace clashes by using c:macro everywhere:
      
      basically, when using it, we can't have something like:
      
      	.. c:struct:: pwm_capture
      
      	.. c:macro:: pwm_capture
      
      So, we need to use, instead:
      
      	.. c:function:: int pwm_capture (struct pwm_device * pwm, struct pwm_capture * result, unsigned long timeout)
      
      for the function declaration.
      
      The kernel-doc change was proposed by Jakob Lykke Andersen here:
      
      	https://github.com/jakobandersen/linux_docs/commit/6fd2076ec001cca7466857493cd678df4dfe4a65
      
      Although I did a different implementation.
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      6e9e4158
    • Mauro Carvalho Chehab's avatar
      scripts: kernel-doc: fix line number handling · 5ef09c96
      Mauro Carvalho Chehab authored
      Address several issues related to pointing to the wrong line
      number:
      
      1) ensure that line numbers will always be initialized
      
         When section is the default (Description), the line number
         is not initializing, producing this:
      
      	$ ./scripts/kernel-doc --enable-lineno ./drivers/media/v4l2-core/v4l2-mem2mem.c|less
      
      	**Description**
      
      	#define LINENO 0
      	In case of streamoff or release called on any context,
      	1] If the context is currently running, then abort job will be called
      	2] If the context is queued, then the context will be removed from
      	   the job_queue
      
        Which is not right. Ensure that the line number will always
        be there. After applied, the result now points to the right location:
      
      	**Description**
      
      	#define LINENO 410
      	In case of streamoff or release called on any context,
      	1] If the context is currently running, then abort job will be called
      	2] If the context is queued, then the context will be removed from
      	   the job_queue
      
      2) The line numbers for function prototypes are always + 1,
         because it is taken at the line after handling the prototype.
         Change the logic to point to the next line after the /** */
         block;
      
      3) The "DOC:" line number should point to the same line as this
         markup is found, and not to the next one.
      
      Probably part of the issues were due to a but that was causing
      the line number offset to be incremented by one, if --export
      were used.
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      5ef09c96
    • Mauro Carvalho Chehab's avatar
      scripts: kernel-doc: allow passing desired Sphinx C domain dialect · 93351d41
      Mauro Carvalho Chehab authored
      When kernel-doc is called via kerneldoc.py, there's no need to
      auto-detect the Sphinx version, as the Sphinx module already
      knows it. So, add an optional parameter to allow changing the
      Sphinx dialect.
      
      As kernel-doc can also be manually called, keep the auto-detection
      logic if the parameter was not specified. On such case, emit
      a warning if sphinx-build can't be found at PATH.
      
      I ended using a suggestion from Joe for using a more readable
      regex, instead of using a complex one with a hidden group like:
      
      	m/^(\d+)\.(\d+)(?:\.?(\d+)?)/
      
      in order to get the optional <patch> argument.
      
      Thanks-to: Joe Perches <joe@perches.com>
      Suggested-by: default avatarJonathan Corbet <corbet@lwn.net>
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      93351d41
    • Mauro Carvalho Chehab's avatar
      scripts: kernel-doc: don't mangle with parameter list · ed8348e2
      Mauro Carvalho Chehab authored
      While kernel-doc needs to parse parameters in order to
      identify its name, it shouldn't be touching the type,
      as parsing it is very difficult, and errors happen.
      
      One current error is when parsing this parameter:
      
      	const u32 (*tab)[256]
      
      Found at ./lib/crc32.c, on this function:
      
      	u32 __pure crc32_be_generic (u32 crc, unsigned char const *p, size_t len, const u32 (*tab)[256], u32 polynomial);
      
      The current logic mangles it, producing this output:
      
      	const u32 ( *tab
      
      That's something that it is not recognizeable.
      
      So, instead, let's push the argument as-is, and use it
      when printing the function prototype and when describing
      each argument.
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      ed8348e2
    • Mauro Carvalho Chehab's avatar
      scripts: kernel-doc: fix typedef identification · 47bcacfd
      Mauro Carvalho Chehab authored
      Some typedef expressions are output as normal functions.
      
      As we need to be clearer about the type with Sphinx 3.x,
      detect such cases.
      
      While here, fix a wrongly-indented block.
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      47bcacfd