On Thu, 2008-12-18 at 10:57 -0800, Randy Dunlap wrote: > From: Randy Dunlap <randy.dunlap@xxxxxxxxxx> > > Add info on how to use DOC: sections in kernel-doc. > DOC: sections enable the addition of inline source file comments > that are general in nature instead of being specific to a > function, struct, union, enum, or typedef. Nice, thanks for the documentation Randy, looks great to me. > Signed-off-by: Randy Dunlap <randy.dunlap@xxxxxxxxxx> > cc: Johannes Berg <johannes@xxxxxxxxxxxxxxxx> > --- > Documentation/kernel-doc-nano-HOWTO.txt | 29 +++++++++++++++++++++++++++++ > 1 file changed, 29 insertions(+) > > --- linux-next-20081218.orig/Documentation/kernel-doc-nano-HOWTO.txt > +++ linux-next-20081218/Documentation/kernel-doc-nano-HOWTO.txt > @@ -282,6 +282,32 @@ struct my_struct { > }; > > > +Including documentation blocks in source files > +---------------------------------------------- > + > +To facilitate having source code and comments close together, you can > +include kernel-doc documentation blocks that are free-form comments > +instead of being kernel-doc for functions, structures, unions, > +enums, or typedefs. This could be used for something like a > +theory of operation for a driver or library code, for example. > + > +This is done by using a DOC: section keyword with a section title. E.g.: > + > +/** > + * DOC: Theory of Operation > + * > + * The whizbang foobar is a dilly of a gizmo. It can do whatever you > + * want it to do, at any time. It reads your mind. Here's how it works. > + * > + * foo bar splat > + * > + * The only drawback to this gizmo is that is can sometimes damage > + * hardware, software, or its subject(s). > + */ > + > +DOC: sections are used in SGML templates files as indicated below. > + > + > How to make new SGML template files > ----------------------------------- > > @@ -302,6 +328,9 @@ exported using EXPORT_SYMBOL. > !F<filename> <function [functions...]> is replaced by the > documentation, in <filename>, for the functions listed. > > +!P<filename> <section title> is replaced by the contents of the DOC: > +section titled <section title> from <filename>. > +Spaces are allowed in <section title>; do not quote the <section title>. > > Tim. > */ <twaugh@xxxxxxxxxx> >
Attachment:
signature.asc
Description: This is a digitally signed message part