Am 19.09.2016 um 17:00 schrieb Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxx>: >> 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. > >> >> 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). >> I tested this with my linuxdoc tools (parser) with I get no >> error messages from the sphinx c-domain. >> >> BTW: >> >> The parser of my linuxdoc project is more strict and spit out some >> warnings, which are not detected by the kernel-doc parser from the >> kernel source tree. >> >> For your rework on kernel-doc comments, it might be helpful to see >> those messages, so I recommend to install the linuxdoc package and >> do some lint. >> >> install: https://return42.github.io/linuxdoc/install.html >> lint: https://return42.github.io/linuxdoc/cmd-line.html#kernel-lintdoc > > Interesting! Yeah, it caught a lot more errors ;) > > If I understood it right, I could do something like: > > diff --git a/Documentation/media/conf_nitpick.py b/Documentation/media/conf_nitpick.py > index 480d548af670..2de603871536 100644 > --- a/Documentation/media/conf_nitpick.py > +++ b/Documentation/media/conf_nitpick.py > @@ -107,3 +107,9 @@ nitpick_ignore = [ > > ("c:type", "v4l2_m2m_dev"), > ] > + > + > +extensions.append("linuxdoc.rstKernelDoc") > +extensions.append("linuxdoc.rstFlatTable") > +extensions.append("linuxdoc.kernel_include") > +extensions.append("linuxdoc.manKernelDoc") > > Right? 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 -- >> 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 -- 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
