Skip to content
  • Mauro Carvalho Chehab's avatar
    docs-rst: kernel-doc: better output struct members · 6d232c80
    Mauro Carvalho Chehab authored
    
    
    Right now, for a struct, kernel-doc produces the following output:
    
    	.. c:type:: struct v4l2_prio_state
    
    	   stores the priority states
    
    	**Definition**
    
    	::
    
    	  struct v4l2_prio_state {
    	    atomic_t prios[4];
    	  };
    
    	**Members**
    
    	``atomic_t prios[4]``
    	  array with elements to store the array priorities
    
    Putting a member name in verbatim and adding a continuation line
    causes the LaTeX output to generate something like:
    	item[atomic_t prios\[4\]] array with elements to store the array priorities
    
    Everything inside "item" is non-breakable, with may produce
    lines bigger than the column width.
    
    Also, for function members, like:
    
            int (* rx_read) (struct v4l2_subdev *sd, u8 *buf, size_t count,ssize_t *num);
    
    It puts the name of the member at the end, like:
    
            int (*) (struct v4l2_subdev *sd, u8 *buf, size_t count,ssize_t *num) read
    
    With is very confusing.
    
    The best is to highlight what really matters: the member name.
    is a secondary information.
    
    So, change kernel-doc, for it to produce the output on a different way:
    
    	**Members**
    
    	``prios[4]``
    
    	  array with elements to store the array priorities
    
    Also, as the type is not part of LaTeX "item[]", LaTeX will split it into
    multiple lines, if needed.
    
    So, both LaTeX/PDF and HTML outputs will look good.
    
    It should be noticed, however, that the way Sphinx LaTeX output handles
    things like:
    
    	Foo
    	   bar
    
    is different than the HTML output. On HTML, it will produce something
    like:
    
    	**Foo**
    	   bar
    
    While, on LaTeX, it puts both foo and bar at the same line, like:
    
    	**Foo** bar
    
    Signed-off-by: default avatarMauro Carvalho Chehab <mchehab@s-opensource.com>
    Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
    6d232c80