1. 01 Sep, 2016 2 commits
    • Mauro Carvalho Chehab's avatar
      docs-rst: kernel-doc: fix typedef output in RST format · 82801d06
      Mauro Carvalho Chehab authored
      When using a typedef function like this one:
      	typedef bool v4l2_check_dv_timings_fnc (const struct v4l2_dv_timings * t, void * handle);
      
      The Sphinx C domain expects it to create a c:type: reference,
      as that's the way it creates the type references when parsing
      a c:function:: declaration.
      
      So, a declaration like:
      
      	.. c:function:: bool v4l2_valid_dv_timings (const struct v4l2_dv_timings * t, const struct v4l2_dv_timings_cap * cap, v4l2_check_dv_timings_fnc fnc, void * fnc_handle)
      
      Will create a cross reference for :c:type:`v4l2_check_dv_timings_fnc`.
      
      So, when outputting such typedefs in RST format, we need to handle
      this special case, as otherwise it will produce those warnings:
      
      	./include/media/v4l2-dv-timings.h:43: WARNING: c:type reference target not found: v4l2_check_dv_timings_fnc
      	./include/media/v4l2-dv-timings.h:60: WARNING: c:type reference target not found: v4l2_check_dv_timings_fnc
      	./include/media/v4l2-dv-timings.h:81: WARNING: c:type reference target not found: v4l2_check_dv_timings_fnc
      
      So, change the kernel-doc script to produce a RST output for the
      above typedef as:
      	.. c:type:: v4l2_check_dv_timings_fnc
      
      	   **Typedef**: timings check callback
      
      	**Syntax**
      
      	  ``bool v4l2_check_dv_timings_fnc (const struct v4l2_dv_timings * t, void * handle);``
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab@s-opensource.com>
      Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
      82801d06
    • Mauro Carvalho Chehab's avatar
      docs-rst: improve typedef parser · d37c43ce
      Mauro Carvalho Chehab authored
      Improve the parser to handle typedefs like:
      
      	typedef bool v4l2_check_dv_timings_fnc(const struct v4l2_dv_timings *t, void *handle);
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab@s-opensource.com>
      Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
      d37c43ce
  2. 25 Aug, 2016 1 commit
  3. 24 Aug, 2016 1 commit
    • 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
  4. 22 Aug, 2016 10 commits
  5. 19 Aug, 2016 1 commit
  6. 18 Aug, 2016 25 commits