On 02/11/15 00:23, Robert P. J. Day wrote: > 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 ... OK, I just haven't checked closely enough then. > 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? I would just remove the unneeded file references from *.tmpl. > 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 > $ Yes, I've seen all of those. -- ~Randy -- 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
