Randy Dunlap wrote: > Boaz Harrosh wrote: >> Boaz Harrosh wrote: >>> Sam Ravnborg wrote: >>>>> +EXPORT_SYMBOL(osd_dev_init); >>>> kernel-doc comments for all exported funtions / variables. >>>> >>> I have some kernel-doc comments of exported functions in the Header >>> file. I have not yet finished all of them. (Laziness on my part). >>> >>> Are kernel-doc comments in headers a big NO-NO. I like it this way, >>> so when I have to learn a new Library all the information >>> I need to know is in the header. Also the header is a much better place >>> when you do programing by shopping, that is you don't know what you need >>> and you look for what's available. >>> >>> Thanks >>> Boaz >> Sam please comment if kernel-doc comments are OK in headers > > Hi, > > The de facto standard for kernel-doc comments is at the implementation site, > which means normally in .c files, except for macros or inline functions. > > Sure you can find some exceptions to that. And there is no hard requirement > in Documentation/kernel-doc-nano-HOWTO.txt. > > IMO the biggest concern is making sure that the (kernel-doc) comments are > updated when the function implementation changes (if updates are needed). > Where would be the best place for this to be more likely to happen? > Usually at the function implementation, I would say. > > ~Randy > > Thanks Randy I would like to keep them in the Headers then. This is because I make sure that the implementation includes the declaring header, so any miss-matches are caught by the compiler. And because these are all library routines exported to other modules. The important thing is the API you linked with. If the API/parametrization change it must first change in the header. The internal implementation is not documented only the external black-box functionality is documented in these places. I will think about it some more, but for now, if it's OK I would like to keep them like submitted. In this particular library they make more sense to me in the header. Boaz -- 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
