diff options
author | Randy Dunlap <randy.dunlap@oracle.com> | 2009-01-06 14:42:43 -0800 |
---|---|---|
committer | Linus Torvalds <torvalds@linux-foundation.org> | 2009-01-06 15:59:28 -0800 |
commit | 28f4d75a618e52f93d8e4a3e7bc66db8c882d679 (patch) | |
tree | 4e1009460067ee7883a9ea9f339881b06effa68e | |
parent | 58cc855c395fc22db996cc893134c4c690f0f0dc (diff) | |
download | linux-28f4d75a618e52f93d8e4a3e7bc66db8c882d679.tar.gz linux-28f4d75a618e52f93d8e4a3e7bc66db8c882d679.tar.bz2 linux-28f4d75a618e52f93d8e4a3e7bc66db8c882d679.zip |
documentation: how to use DOC: section blocks
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.
Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Cc: Johannes Berg <johannes@sipsolutions.net>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
-rw-r--r-- | Documentation/kernel-doc-nano-HOWTO.txt | 29 |
1 files changed, 29 insertions, 0 deletions
diff --git a/Documentation/kernel-doc-nano-HOWTO.txt b/Documentation/kernel-doc-nano-HOWTO.txt index 4115a4a80eb6..d73fbd2b2b45 100644 --- a/Documentation/kernel-doc-nano-HOWTO.txt +++ b/Documentation/kernel-doc-nano-HOWTO.txt @@ -287,6 +287,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 ----------------------------------- @@ -307,6 +333,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@redhat.com> |