docs-rst: kernel-doc: better output struct members
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: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
			
			
This commit is contained in:
		
							parent
							
								
									ca7bfe2c8d
								
							
						
					
					
						commit
						6d232c8015
					
				| @ -2000,7 +2000,7 @@ sub output_struct_rst(%) { | ||||
| 	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; | ||||
| 	$type = $args{'parametertypes'}{$parameter}; | ||||
|         print_lineno($parameterdesc_start_lines{$parameter_name}); | ||||
| 	print "``$type $parameter``\n"; | ||||
| 	print "``" . $parameter . "``\n"; | ||||
| 	output_highlight_rst($args{'parameterdescs'}{$parameter_name}); | ||||
| 	print "\n"; | ||||
|     } | ||||
|  | ||||
		Loading…
	
		Reference in New Issue
	
	Block a user