Am 19.09.2016 um 17:00 schrieb Mauro Carvalho Chehab [off-list ref]:

quoted

Hmm, as far as I see, the output is not correct ... The output of
functions with a function pointer argument are missing the 
leading parenthesis in the function definition:

 .. c:function:: struct v4l2_m2m_ctx * v4l2_m2m_ctx_init (struct v4l2_m2m_dev * m2m_dev, void * drv_priv, int (*queue_init) (void *priv, struct vb2_queue *src_vq, struct vb2_queue *dst_vq)

The missing parenthesis cause the error message. 

Ah, OK! I'll kernel-doc and see what's happening here.

quoted

The output of the parameter description is:

 ``int (*)(void *priv, struct vb2_queue *src_vq, struct vb2_queue *dst_vq) queue_init``
   a callback for queue type-specific initialization function
   to be used for initializing videobuf_queues

Correct (and IMO better to read) is:

 .. c:function:: struct v4l2_m2m_ctx *v4l2_m2m_ctx_init(struct v4l2_m2m_dev *m2m_dev, void *drv_priv, int (*queue_init)(void *priv, struct vb2_queue *src_vq, struct vb2_queue *dst_vq))

and the parameter description should be something like ...

  :param int (\*queue_init)(void \*priv, struct vb2_queue \*src_vq, struct vb2_queue \*dst_vq):
       a callback for queue type-specific initialization function
       to be used for initializing videobuf_queues

I guess the better would be to strip the parameter type and output
it as:
	queue_init
		a callback for queue type-specific initialization function
		to be used for initializing videobuf_queues

Good point!

As I pointed before, the point is that such argument can easily have
more than 80 columns, with would cause troubles with LaTeX output,
as LaTeX doesn't break long verbatim text on multiple lines.

I submitted one patch fixing it. Not sure if it got merged by Jon
or not.

Ups, I might have overseen this patch .. as Jon said, its hard to
follow you ;)

I tested the above with Jon's docs-next, so it seems your patch is
not yet applied. Could you send me a link for this patch? (sorry,
I can't find it).

No ;)

It would be good to do some sort of logic on the
above for it to automatically include it, if linuxdoc is
present, otherwise print a warning and do "just" the normal
Sphinx tests.

The intention is; with installing the linuxdoc project you get
some nice command line tools, like lint for free and if you want
to see how the linuxdoc project compiles your kernel documentation
and how e.g. man pages are build or what warnings are spit, you
have to **replace** the extensions from the kernel's source with
the one from the linuxdoc project.

This is done by patching the build scripts as described in:

  https://return42.github.io/linuxdoc/linux.html

FYI: I updated the documentation of the linuxdoc project.

In this project I develop and maintain "future" concepts like
man-page builder and the py-version of the kernel-doc parser. 
Vice versa, every improvement I see on kernel's source tree is
merged into this project.

This project is also used by my POC at:

* http://return42.github.io/sphkerneldoc/

E.g. it builds the documentation of the complete kernel sources

* http://return42.github.io/sphkerneldoc/linux_src_doc/index.html

the last one is also my test-case to find regression when I change
something / running against the whole source tree and compare the
result to the versioned reST files at 

* https://github.com/return42/sphkerneldoc/tree/master/doc/linux_src_doc

-- Markus --

quoted

E.g. if you want to lint your whole include/media tree type:

 kernel-lintdoc [--sloppy] include/media

Yeah, running it manually is another way, although I prefer to have
it done via a Makefile target, and doing only for the files that
are currently inside a Sphinx rst file (at least on a first moment).

Thanks,
Mauro