On Thursday 25 October 2007 3:49:26 pm Randy Dunlap wrote: > On Thu, 25 Oct 2007 16:40:35 -0500 Rob Landley wrote: > > On Thursday 25 October 2007 12:32:41 pm Randy Dunlap wrote: > > > > Entirely possible I'm doing something wrong: > > > > > > > > <sect1 id="scsi_device.h"> > > > > <title>include/scsi/scsi_device.h</title> > > > > <para> > > > > </para> > > > > !Einclude/scsi/scsi_device.h > > > > </sect1> > > > > > > !E is for exported symbols and that file has none. > > > USe !I instead. > > > > So how do I handle a case like drivers/ata/libata-core.c which has > > EXPORT_SYMBOL() calls for functions that live in (and are documented in) > > other files, such as ata_scsi_ioctl() in drivers/ata/libata-scsi.c? > > I don't see ata_scsi_ioctl() documented at all. Are you looking at > a newer tree than I am? (i'm using 2.6.24-rc1) No, I mean I was thinking of adding a kerneldoc comment and noticed the discrepancy. As for already checked-in stuff, substitute ata_std_bios_param, ata_scsi_slave_config, and ata_scsi_slave_destroy. Each of those functions has a kerneldoc comment in libata-scsi.c, but the export statement for that function is in libata-core.c. > Long-term answer is that we prefer EXPORT_SYMBOL() to be used > just under the function that is being exported. In this case, > the maintainer may be disagreeing with that. [cc-ed] Moving the EXPORT_SYMBOL()s would be nice. The documentation tools don't preserve context outside of a single file, and I'd like to get full coverage documenting exported symbols before worrying much about internal ones... > Short-term answer is to use !Isource_filename_where_kernel_doc_is > as though it's not EXPORTed. I think. Except if the EXPORTs got moved/fixed it would then hide them from !I without generating any kind of warning. Actually, for the really short term I can go "see the existing libata book in this directory" and foist this problem off on Jeff Garzik. :) (Friday deadline.) Rob -- "One of my most productive days was throwing away 1000 lines of code." - Ken Thompson. - To unsubscribe from this list: send the line "unsubscribe linux-scsi" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
