From 28f4d75a618e52f93d8e4a3e7bc66db8c882d679 Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Tue, 6 Jan 2009 14:42:43 -0800 Subject: [PATCH] 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 Cc: Johannes Berg Signed-off-by: Andrew Morton Signed-off-by: Linus Torvalds --- Documentation/kernel-doc-nano-HOWTO.txt | 29 +++++++++++++++++++++++++ 1 file changed, 29 insertions(+) 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 is replaced by the documentation, in , for the functions listed. +!P
is replaced by the contents of the DOC: +section titled
from . +Spaces are allowed in
; do not quote the
. Tim. */