On Fri, 03 Jun 2016, Jonathan Corbet <corbet@xxxxxxx> wrote: > [So I'm finally trying to get into this for real, hopefully I won't be > interrupted too many times...expect a few mails as I catch up.] > > On Fri, 20 May 2016 16:39:31 +0300 > Jani Nikula <jani.nikula@xxxxxxxxx> wrote: > >> There are a few tradeoffs, of course. First, this requires that the >> EXPORT_SYMBOL markers are placed immediately after the function being >> exported, as kernel-doc will only look at one file at a time. This is >> the recommendation anyway. > > As I understand it, the technical reasons that kept some markers in > separate files should no longer be relevant, so this is probably OK. It > would be nice to have a sense for how many sites need to be fixed. Actually, mostly this is not a problem due to EXPORT_SYMBOL placement, but rather due to kernel-doc comments being placed in header files above function declarations while EXPORT_SYMBOL is where it should be next to the function definition. I don't think we can force people to move the kernel-doc comments for exported functions from header files next to the function definitions. The straightforward fix to this is to add an optional filename parameter to the kernel-doc extension :export: argument, to pass additional files to kernel-doc where to look for the EXPORT_SYMBOLs. For example: .. kernel-doc:: include/drm/foo.h :export: drivers/gpu/drm/foo/foo.c drivers/gpu/drm/foo/bar.c This would instruct kernel-doc to extract documentation from include/drm/foo.h for all functions that have been exported using EXPORT_SYMBOL (or _GPL) in include/drm/foo.h, drivers/gpu/drm/foo/foo.c, or drivers/gpu/drm/foo/bar.c. We have something along these lines in docproc already with the !D directive, so nothing altogether surprising. If my quick grep-fu serves me right, there are about a thousand exported symbols with kernel-doc comments in the headers. It's a ballpark figure. They come in batches; a small fraction of that many filenames in a fraction of the :export: statements would cover most of them. Before this fix, the workaround is to name the functions with :functions: argument instead of using :export:. I'm hoping this is not a blocker for merging the series. If the proposed fix is acceptable, I'll get it done before v4.8. BR, Jani. The ugly greps: $ git grep "^EXPORT_SYMBOL" | sed 's/^[^(]*(\([a-zA-Z0-9_]*\)).*/\1/' | sort > exports $ git grep -h -A1 "^/\*\*$" -- *.h | grep -v "^\(/\*\*\|--\)" | sed 's/^ \*[ ]*\([a-zA-Z0-9_][a-zA-Z0-9_]*\).*/\1/;' | sort > comments $ comm -1 -2 comments exports | wc -l 952 -- Jani Nikula, Intel Open Source Technology Center -- 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
