mbox series

[0/8] Clean up kernel-doc and fix literal-block handling

Message ID 20180207172624.24555-1-corbet@lwn.net
Headers show
Series Clean up kernel-doc and fix literal-block handling | expand

Message

Jonathan Corbet Feb. 7, 2018, 5:26 p.m. UTC 
So once upon a time I set out to fix the problem reported by Tobin wherein
a literal block within a kerneldoc comment would be corrupted in
processing.  On the way, though, I got annoyed at the way I have to learn
how kernel-doc works from the beginning every time I tear into it.

As a result, seven of the following eight patches just get rid of some dead
code and reorganize the rest - mostly turning the 500-line process_file()
function into something a bit more rational.  Sphinx output is unchanged
after these are applied.  Then, at the end, there's a tweak to stop messing
with literal blocks.

If anybody was unaware that I've not done any serious Perl since the
1990's, they will certainly understand that fact now.

Jonathan Corbet (8):
  docs: kernel-doc: Get rid of xml_escape() and friends
  docs: kernel-doc: Rename and split STATE_FIELD
  docs: kernel-doc: Move STATE_NORMAL processing into its own function
  docs: kernel-doc: Move STATE_NAME processing into its own function
  docs: kernel-doc: Move STATE_BODY processing to a separate function
  docs: kernel-doc: Move STATE_PROTO processing into its own function
  docs: kernel-doc: Finish moving STATE_* code out of process_file()
  docs: kernel-doc: Don't mangle literal code blocks in comments

 scripts/kernel-doc | 658 +++++++++++++++++++++++++++++------------------------
 1 file changed, 357 insertions(+), 301 deletions(-)

-- 
2.14.3

Comments

Tobin C. Harding Feb. 8, 2018, 2:26 a.m. UTC | #1 
On Wed, Feb 07, 2018 at 10:26:16AM -0700, Jonathan Corbet wrote:
> So once upon a time I set out to fix the problem reported by Tobin wherein

> a literal block within a kerneldoc comment would be corrupted in

> processing.  On the way, though, I got annoyed at the way I have to learn

> how kernel-doc works from the beginning every time I tear into it.


Awesome. The patch that exposed that problem hasn't landed yet but I
tested this series and can confirm that it fixes it.

FTR to test I did:

- update function docs for include/linux/rcupdate.h:rcu_pointer_hadoff()

  	removed enclosing '``' and added leading '::'

- apply this series
- rebuild docs
- profit

thanks,
Tobin.