From 7b4ff1adb57ad96d8f12a05d8c661a3d8c4d2be1 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 11 May 2017 10:17:45 -0300 Subject: mutex, futex: adjust kernel-doc markups to generate ReST There are a few issues on some kernel-doc markups that was causing troubles with kernel-doc output on ReST format: ./kernel/futex.c:492: WARNING: Inline emphasis start-string without end-string. ./kernel/futex.c:1264: WARNING: Block quote ends without a blank line; unexpected unindent. ./kernel/futex.c:1721: WARNING: Block quote ends without a blank line; unexpected unindent. ./kernel/futex.c:2338: WARNING: Block quote ends without a blank line; unexpected unindent. ./kernel/futex.c:2426: WARNING: Block quote ends without a blank line; unexpected unindent. ./kernel/futex.c:2899: WARNING: Block quote ends without a blank line; unexpected unindent. ./kernel/futex.c:2972: WARNING: Block quote ends without a blank line; unexpected unindent. Fix them. No functional changes. Acked-by: Darren Hart (VMware) Signed-off-by: Mauro Carvalho Chehab --- include/linux/mutex.h | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'include') diff --git a/include/linux/mutex.h b/include/linux/mutex.h index 1127fe31645d..ffcba1f337da 100644 --- a/include/linux/mutex.h +++ b/include/linux/mutex.h @@ -214,9 +214,9 @@ enum mutex_trylock_recursive_enum { * raisins, and once those are gone this will be removed. * * Returns: - * MUTEX_TRYLOCK_FAILED - trylock failed, - * MUTEX_TRYLOCK_SUCCESS - lock acquired, - * MUTEX_TRYLOCK_RECURSIVE - we already owned the lock. + * - MUTEX_TRYLOCK_FAILED - trylock failed, + * - MUTEX_TRYLOCK_SUCCESS - lock acquired, + * - MUTEX_TRYLOCK_RECURSIVE - we already owned the lock. */ static inline /* __deprecated */ __must_check enum mutex_trylock_recursive_enum mutex_trylock_recursive(struct mutex *lock) -- cgit v1.2.3 From 771b00a84be46d10e3f74af2d86d226302c907c5 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 12 May 2017 09:19:29 -0300 Subject: net: skbuff.h: properly escape a macro name on kernel-doc The "%" escape code of kernel-doc only handle letters. It doesn't handle special chars. So, use the ``literal`` notation. That fixes this warning: ./include/linux/skbuff.h:2695: WARNING: Inline literal start-string without end-string. No functional changes. Signed-off-by: Mauro Carvalho Chehab --- include/linux/skbuff.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'include') diff --git a/include/linux/skbuff.h b/include/linux/skbuff.h index a098d95b3d84..25b1659c832a 100644 --- a/include/linux/skbuff.h +++ b/include/linux/skbuff.h @@ -2691,7 +2691,7 @@ bool skb_page_frag_refill(unsigned int sz, struct page_frag *pfrag, gfp_t prio); * @offset: the offset within the fragment (starting at the * fragment's own offset) * @size: the number of bytes to map - * @dir: the direction of the mapping (%PCI_DMA_*) + * @dir: the direction of the mapping (``PCI_DMA_*``) * * Maps the page associated with @frag to @device. */ -- cgit v1.2.3 From d651983dde41a854e25664d98cbfc999d55785a8 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 12 May 2017 09:35:46 -0300 Subject: net: fix some identation issues at kernel-doc markups Sphinx is very pedantic with regards to identation and escape sequences: ./include/net/sock.h:1967: ERROR: Unexpected indentation. ./include/net/sock.h:1969: ERROR: Unexpected indentation. ./include/net/sock.h:1970: WARNING: Block quote ends without a blank line; unexpected unindent. ./include/net/sock.h:1971: WARNING: Block quote ends without a blank line; unexpected unindent. ./include/net/sock.h:2268: WARNING: Inline emphasis start-string without end-string. ./net/core/sock.c:2686: ERROR: Unexpected indentation. ./net/core/sock.c:2687: WARNING: Block quote ends without a blank line; unexpected unindent. ./net/core/datagram.c:182: WARNING: Inline emphasis start-string without end-string. ./include/linux/netdevice.h:1444: ERROR: Unexpected indentation. ./drivers/net/phy/phy.c:381: ERROR: Unexpected indentation. ./drivers/net/phy/phy.c:382: WARNING: Block quote ends without a blank line; unexpected unindent. - Fix spacing where needed; - Properly escape constants; - Use a literal block for a race description. No functional changes. Signed-off-by: Mauro Carvalho Chehab --- include/linux/netdevice.h | 9 +++++---- include/net/sock.h | 9 ++++----- 2 files changed, 9 insertions(+), 9 deletions(-) (limited to 'include') diff --git a/include/linux/netdevice.h b/include/linux/netdevice.h index 9c23bd2efb56..56d54b6fac45 100644 --- a/include/linux/netdevice.h +++ b/include/linux/netdevice.h @@ -1433,13 +1433,14 @@ enum netdev_priv_flags { /** * struct net_device - The DEVICE structure. - * Actually, this whole structure is a big mistake. It mixes I/O - * data with strictly "high-level" data, and it has to know about - * almost every data structure used in the INET module. + * + * Actually, this whole structure is a big mistake. It mixes I/O + * data with strictly "high-level" data, and it has to know about + * almost every data structure used in the INET module. * * @name: This is the first field of the "visible" part of this structure * (i.e. as seen by users in the "Space.c" file). It is the name - * of the interface. + * of the interface. * * @name_hlist: Device name hash chain, please keep it close to name[] * @ifalias: SNMP alias diff --git a/include/net/sock.h b/include/net/sock.h index 66349e49d468..9ca99b5c1328 100644 --- a/include/net/sock.h +++ b/include/net/sock.h @@ -1953,11 +1953,10 @@ static inline bool sk_has_allocations(const struct sock *sk) * The purpose of the skwq_has_sleeper and sock_poll_wait is to wrap the memory * barrier call. They were added due to the race found within the tcp code. * - * Consider following tcp code paths: + * Consider following tcp code paths:: * - * CPU1 CPU2 - * - * sys_select receive packet + * CPU1 CPU2 + * sys_select receive packet * ... ... * __add_wait_queue update tp->rcv_nxt * ... ... @@ -2264,7 +2263,7 @@ void __sock_tx_timestamp(__u16 tsflags, __u8 *tx_flags); * @tsflags: timestamping flags to use * @tx_flags: completed with instructions for time stamping * - * Note : callers should take care of initial *tx_flags value (usually 0) + * Note: callers should take care of initial ``*tx_flags`` value (usually 0) */ static inline void sock_tx_timestamp(const struct sock *sk, __u16 tsflags, __u8 *tx_flags) -- cgit v1.2.3 From b6f6c29454d236e85f2912cb0f9366825ca1b0be Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sat, 13 May 2017 07:40:36 -0300 Subject: mtd: adjust kernel-docs to avoid Sphinx/kerneldoc warnings ./drivers/mtd/nand/nand_bbt.c:1: warning: no structured comments found ./include/linux/mtd/nand.h:785: ERROR: Unexpected indentation. ./drivers/mtd/nand/nand_base.c:449: WARNING: Definition list ends without a blank line; unexpected unindent. ./drivers/mtd/nand/nand_base.c:1161: ERROR: Unexpected indentation. ./drivers/mtd/nand/nand_base.c:1162: WARNING: Block quote ends without a blank line; unexpected unindent. Signed-off-by: Mauro Carvalho Chehab --- include/linux/mtd/nand.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'include') diff --git a/include/linux/mtd/nand.h b/include/linux/mtd/nand.h index 9591e0fbe5bd..3d5b20379ba3 100644 --- a/include/linux/mtd/nand.h +++ b/include/linux/mtd/nand.h @@ -779,7 +779,7 @@ nand_get_sdr_timings(const struct nand_data_interface *conf) * Minimum amount of bit errors per @ecc_step_ds guaranteed * to be correctable. If unknown, set to zero. * @ecc_step_ds: [INTERN] ECC step required by the @ecc_strength_ds, - * also from the datasheet. It is the recommended ECC step + * also from the datasheet. It is the recommended ECC step * size, if known; if unknown, set to zero. * @onfi_timing_mode_default: [INTERN] default ONFI timing mode. This field is * set to the actually used ONFI mode if the chip is -- cgit v1.2.3 From 19285f3c4669c8b0cea8fb6c452c83db9e6386be Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sun, 14 May 2017 11:52:56 -0300 Subject: ata: update references for libata documentation The libata documentation is now using ReST. Update references to it to point to the new place. Signed-off-by: Mauro Carvalho Chehab --- include/linux/ata.h | 2 +- include/linux/libata.h | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) (limited to 'include') diff --git a/include/linux/ata.h b/include/linux/ata.h index ad7d9ee89ff0..73fe18edfdaf 100644 --- a/include/linux/ata.h +++ b/include/linux/ata.h @@ -20,7 +20,7 @@ * * * libata documentation is available via 'make {ps|pdf}docs', - * as Documentation/DocBook/libata.* + * as Documentation/driver-api/libata.rst * * Hardware documentation available from http://www.t13.org/ * diff --git a/include/linux/libata.h b/include/linux/libata.h index c9a69fc8821e..9e6633235ad7 100644 --- a/include/linux/libata.h +++ b/include/linux/libata.h @@ -19,7 +19,7 @@ * * * libata documentation is available via 'make {ps|pdf}docs', - * as Documentation/DocBook/libata.* + * as Documentation/driver-api/libata.rst * */ -- cgit v1.2.3 From e1b4fc7add72f565d9c35066d85108346e01d3e9 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sun, 14 May 2017 12:04:55 -0300 Subject: fs: update location of filesystems documentation The filesystem documentation was moved from DocBook to Documentation/filesystems/. Update it at the sources. Signed-off-by: Mauro Carvalho Chehab --- include/linux/debugfs.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'include') diff --git a/include/linux/debugfs.h b/include/linux/debugfs.h index 9174b0d28582..aa86e6d8c1aa 100644 --- a/include/linux/debugfs.h +++ b/include/linux/debugfs.h @@ -9,7 +9,7 @@ * 2 as published by the Free Software Foundation. * * debugfs is for people to use instead of /proc or /sys. - * See Documentation/DocBook/filesystems for more details. + * See Documentation/filesystems/ for more details. */ #ifndef _DEBUGFS_H_ -- cgit v1.2.3