Re: RFC? [PATCH] docs-rst: kernel-doc: better output struct members

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



Am 22.08.2016 um 12:06 schrieb Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx>:

> Markus,
> 
> Em Mon, 22 Aug 2016 10:56:01 +0200
> Markus Heiser <markus.heiser@xxxxxxxxxxx> escreveu:
> 
>> Am 21.08.2016 um 14:11 schrieb Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx>:
>> 
>>> 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  
>> 
>> 
>> Right now, the description of C-struct members is a simple rest-definition-list 
>> (not in the c-domain). It might be better to use the c-domain for members:
>> 
>>  http://www.sphinx-doc.org/en/stable/domains.html#directive-c:member
>> 
>> But this is not the only thing we have to consider. To make a valid C-struct
>> description (with targets/references in the c-domain) we need a more
>> *structured* reST markup where the members are described in the block-content
>> of the struct directive. E.g:
>> 
>> <SNIP> -----------
>> |.. c:type:: struct v4l2_subdev_ir_ops
>> |
>> |   operations for IR subdevices
>> |
>> |   .. c:member::  int (* rx_read) (struct v4l2_subdev *sd, u8 *buf, size_t count,ssize_t *num)
>> |
>> <SNIP> -----------
>> 
>> By this small example, you see, that we have to discuss the whole markup 
>> produced by the kernel-doc script (function arguments, unions etc.). 
>> IMHO, since kernel-doc is widely used, this should be a RFC.
> 
> I tried using c:member. It won't work on LaTeX output, as it will
> still put everything into a LaTeX item, with doesn't do line breaks.
> 
> Also, according to Sphinx manual at http://www.sphinx-doc.org/en/stable/domains.html
> The syntax is:
> 
> 	.. c:member:: type name
> 
> 	    Describes a C struct member. Example signature:
> 
> 		.. c:member:: PyObject* PyTypeObject.tp_bases
> 
> So, it expects <type> <member> as arguments. If the manual is right, it
> would be expecting, instead, the weird syntax:
> 
>   .. c:member::  int (*) (struct v4l2_subdev *sd, u8 *buf, size_t count,ssize_t *num) rx_read
> 
> With hurts my eyes.

Argh, you are right ... but it is very confusing. I made a small test::


<SNIP> ------------

.. c:type:: struct v4l2_subdev_ir_ops_001

   .. c:member::  int (*) (struct v4l2_subdev *sd, u8 *buf, size_t count,ssize_t *num) rx_read

      lorem ipsum


.. c:type:: struct v4l2_subdev_ir_ops_002

   operations for IR subdevices

   .. c:member::  int (* rx_read) (struct v4l2_subdev *sd, u8 *buf, size_t count,ssize_t *num)

      lorem ipsum


Test refs
=========

* :c:member:`v4l2_subdev_ir_ops_001.rx_read`
* :c:member:`v4l2_subdev_ir_ops_002.rx_read`

<SNIP> ------------


It seems, the c-parser is very dump, the v4l2_subdev_ir_ops_002.rx_read link
is closed, the 001 not ... a look at the sources:

* reg-exprs: https://github.com/sphinx-doc/sphinx/blob/master/sphinx/domains/c.py#L29

And the following snippet is all about handling signatures (of func, type, member .. directives)

m = c_funcptr_sig_re.match(sig)
if m is None:
    m = c_sig_re.match(sig)
if m is None:
    raise ValueError('no match')
rettype, name, arglist, const = m.groups()

In short: since the signature parsing is such worse, we can't predict
how type and name is parsed ... argh.

> As I guess we don't want to maintain ourselves a LaTeX output Sphinx
> plugin forked from upstream,

Agree

> I guess that a more definitive solution
> would involve overriding  the parser for c:member in a way that it would
> produce an output like the one in this path, while creating the proper
> c domain reference for the structure member inside the C domain.

Summarized:

* The c-parser of the Sphinx c-domain, is worse. BTW this is the next
  c-parser implementation used in the toolchain (parse-headers, kernel-doc)
  https://www.mail-archive.com/linux-media@xxxxxxxxxxxxxxx/msg101440.html

* Even if we use a member-directive in the block of a type directive,
  it will nod be rendered well in the latex / pdf output.

OK, with this in mind, I agree with Jani ... "keep it simple" ;-)

-- Markus --


--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html



[Index of Archives]     [Kernel Newbies]     [Security]     [Netfilter]     [Bugtraq]     [Linux FS]     [Yosemite Forum]     [MIPS Linux]     [ARM Linux]     [Linux Security]     [Linux RAID]     [Samba]     [Video 4 Linux]     [Device Mapper]     [Linux Resources]

  Powered by Linux