On Tue, 10 Feb 2015, Randy Dunlap wrote:
> On 02/03/15 11:31, Robert P. J. Day wrote:
> > next, in the current "make htmldocs", there are a few diagnostics
> > like this:
> >
> > Warning(.//drivers/usb/gadget/function/f_acm.c): no structured comments found
> > Warning(.//drivers/usb/gadget/function/f_ecm.c): no structured comments found
> > Warning(.//drivers/usb/gadget/function/f_subset.c): no structured comments found
> > Warning(.//drivers/usb/gadget/function/f_obex.c): no structured comments found
> > Warning(.//drivers/usb/gadget/function/f_serial.c): no structured comments found
> >
> > clearly representing a DocBook .tmpl file pulling in a specified
> > source file that has no (typically exported) kerneldoc content. is
> > there any reason for those lines to be there? shouldn't the .tmpl
> > files be cleansed of "!E" lines that have no value and simply generate
> > dummy/error pages in the manual?
>
> Yes, I have seen those Warning lines. Do they also generate some
> dummy/error pages in the output files? I had not noticed that.
>
> Sure, they can be deleted. I just never thought that they were a
> serious problem, but if they also generate error output in the
> html/pdf etc., then they certainly need to be deleted.
i'm sure i'm not the only one who would see this ... in the example
above, building the gadget.html file, those warnings generate a page
in the "Composite Device Functions" section that contains:
Composite Device Functions
.//drivers/usb/gadget/function/f_acm.c — Document generation inconsistency
.//drivers/usb/gadget/function/f_ecm.c — Document generation inconsistency
.//drivers/usb/gadget/function/f_subset.c — Document generation inconsistency
.//drivers/usb/gadget/function/f_obex.c — Document generation inconsistency
.//drivers/usb/gadget/function/f_serial.c — Document generation inconsistency
... etc ...
so one would think those source files should be kerneldoc'ed, or
refernces to those files should be removed from the gadget.tmpl file.
thoughts either way?
there are a small number of these throughout:
$ grep "no structured comments" /tmp/docs1
Warning(.//sound/soc/soc-cache.c): no structured comments found
Warning(.//kernel/sys.c): no structured comments found
Warning(.//drivers/dma-buf/seqno-fence.c): no structured comments found
Warning(.//drivers/dma-buf/reservation.c): no structured comments found
Warning(.//include/linux/reservation.h): no structured comments found
Warning(.//drivers/gpu/drm/i915/i915_irq.c): no structured comments found
Warning(.//drivers/usb/gadget/function/f_acm.c): no structured comments found
Warning(.//drivers/usb/gadget/function/f_ecm.c): no structured comments found
Warning(.//drivers/usb/gadget/function/f_subset.c): no structured comments found
Warning(.//drivers/usb/gadget/function/f_obex.c): no structured comments found
Warning(.//drivers/usb/gadget/function/f_serial.c): no structured comments found
Warning(.//lib/crc32.c): no structured comments found
Warning(.//arch/s390/include/asm/cmb.h): no structured comments found
Warning(.//drivers/scsi/constants.c): no structured comments found
$
rday
--
========================================================================
Robert P. J. Day Ottawa, Ontario, CANADA
http://crashcourse.ca
Twitter: http://twitter.com/rpjday
LinkedIn: http://ca.linkedin.com/in/rpjday
========================================================================
