summaryrefslogtreecommitdiffstats
path: root/Documentation/kernel-doc-nano-HOWTO.txt
Commit message (Collapse)AuthorAgeFilesLines
* docs: get rid of kernel-doc-nano-HOWTO.txtMauro Carvalho Chehab2017-12-211-322/+0
| | | | | | | | | Everything there is already described at Documentation/doc-guide/kernel-doc.rst. So, there's no reason why to keep it anymore. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: update old references for DocBook from the documentationMauro Carvalho Chehab2017-05-161-54/+11
| | | | | | | | DocBook is mentioned several times at the documentation. Update the obsolete references from it at the DocBook. Acked-by: SeongJae Park <sj38.park@gmail.com> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
* docs-rst: doc-guide: split the kernel-documentation.rst contentsMauro Carvalho Chehab2016-11-191-1/+1
| | | | | | | | | Having the kernel-documentation at the topmost level doesn't allow generating a separate PDF file for it. Also, makes harder to add extra contents. So, place it on a sub-dir. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: deprecate kernel-doc-nano-HOWTO.txtJonathan Corbet2016-07-201-0/+3
| | | | | | | | | | Now that the new Sphinx world order is taking over, the information in kernel-doc-nano-HOWTO.txt is outmoded. I hate to remove it altogether, since it's one of those files that people expect to find. But we can add a warning and fix all the other pointers to it. Reminded-by: Daniel Vetter <daniel.vetter@ffwll.ch> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* Documenation: Update location of docproc.cPeter Huewe2015-07-141-1/+1
| | | | | | | | docproc.c was moved in 2011 from scripts/basic to scripts -> updated the references accordingly Signed-off-by: Peter Huewe <peterhuewe@gmx.de> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* kernel-doc: Update references to SGML to refs to XML instead.Robert P. J. Day2013-05-281-5/+6
| | | | | | | | Since the "sgmldocs" target is simply a pointer to the newer "xmldocs" target, update the documentation to reflect this. Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca> Signed-off-by: Jiri Kosina <jkosina@suse.cz>
* Kernel-doc: Convention: Use a "Return" section to describe return valuesYacine Belkadi2012-11-271-3/+10
| | | | | | | | | | | | | | | | | | | | | | | | | Non-void functions should describe their return values in their kernel-doc comments. Currently, some don't, others do in various forms. For example: * Return the result. * Return: The result. * Returns the result. * Returns: the result. * Return Value: The result. * @return: the result. * This function returns the result. * It will return the result. Defining a convention would improve consistency of kernel-doc comments. It would also help scripts/kernel-doc identify the text describing the return value of a function. Thus allowing additional checks on the comments, and suitable highlighting in the generated docs (man pages, html, etc). So, as a convention, use a section named "Return" to describe the return value of a function. Signed-off-by: Yacine Belkadi <yacine.belkadi.1@gmail.com> Signed-off-by: Rob Landley <rob@landley.net> Signed-off-by: Jiri Kosina <jkosina@suse.cz>
* docbook: warn on unused doc entriesJohannes Berg2010-09-111-0/+5
| | | | | | | | | | | | | | | | | | | | When you don't use !E or !I but only !F, then it's very easy to miss including some functions, structs etc. in documentation. To help finding which ones were missed, allow printing out the unused ones as warnings. For example, using this on mac80211 yields a lot of warnings like this: Warning: didn't use docs for DOC: mac80211 workqueue Warning: didn't use docs for ieee80211_max_queues Warning: didn't use docs for ieee80211_bss_change Warning: didn't use docs for ieee80211_bss_conf when generating the documentation for it. Signed-off-by: Johannes Berg <johannes.berg@intel.com> Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
* documentation: update kernel-doc-nano-HOWTO informationRandy Dunlap2010-01-111-5/+7
| | | | | | | | | | | | Remove comments about function short descriptions not allowed to be on multiple lines (that was fixed/changed recently). Add comments that function "section header:" names need to be unique per function/struct/union/typedef/enum. Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
* kernel-doc: allow multi-line declaration purpose descriptionsJohannes Weiner2009-09-181-1/+3
| | | | | | | | | | | | | | | | | | | | Allow the short description after symbol name and dash in a kernel-doc comment to span multiple lines, e.g. like this: /** * unmap_mapping_range - unmap the portion of all mmaps in the * specified address_space corresponding to the specified * page range in the underlying file. * @mapping: the address space containing mmaps to be unmapped. * ... */ The short description ends with a parameter description, an empty line or the end of the comment block. Signed-off-by: Johannes Weiner <hannes@cmpxchg.org> Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
* kernel-doc: restrict syntax for private: and public:Randy Dunlap2009-05-021-2/+5
| | | | | | | | | | | | | | | | scripts/kernel-doc can (incorrectly) delete struct members that are surrounded by /* ... */ <struct members> /* ... */ if there is a /* private: */ comment in there somewhere also. Fix that by making the "/* private:" only allow whitespace between /* and "private:", not anything/everything in the world. This fixes some erroneous kernel-doc warnings that popped up while processing include/linux/usb/composite.h. Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
* kernel-doc: preferred ending marker and examplesRandy Dunlap2009-02-111-3/+4
| | | | | | | | | | Fix kernel-doc-nano-HOWTO.txt to use */ as the ending marker in kernel-doc examples and state that */ is the preferred ending marker. Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Reported-by: Robert Love <robert.w.love@intel.com> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
* documentation: how to use DOC: section blocksRandy Dunlap2009-01-061-0/+29
| | | | | | | | | | | 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>
* docs: document how to write @varargs in kernel-docRandy Dunlap2009-01-061-0/+5
| | | | | | | | | | Add documentation on how to use kernel-doc for function parameters that are "..." (varargs). Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Cc: Rusty Russell <rusty@rustcorp.com.au> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
* sched: add kernel doc for the completion, fix kernel-doc-nano-HOWTO.txtKevin Diggs2008-08-261-2/+2
| | | | | | | | | | This patch adds kernel doc for the completion feature. An error in the split-man.pl PERL snippet in kernel-doc-nano-HOWTO.txt is also fixed. Signed-off-by: Kevin Diggs <kevdig@hypersurf.com> Signed-off-by: Ingo Molnar <mingo@elte.hu>
* doc: document the kernel-doc conventions for kernel hackersPaul Jackson2008-06-061-0/+99
| | | | | | | | | | | | | | | | | | | | | | | | | | Provide documentation of the kernel-doc documentation conventions oriented to kernel hackers. Since I figure that there will be more people reading this kernel-doc-nano-HOWTO.txt file who are kernel developers focused on the rest of the kernel, than there will be readers of this file who are documentation developers extracting that embedded kernel-doc documentation, I have taken the liberty of making the new section added here: How to format kernel-doc comments the first section of the kernel-doc-nano-HOWTO.txt file. This first section is intended to introduce, motivate and provide basic usage of the kernel-doc mechanism for kernel hackers developing other portions of the kernel. Signed-off-by: Paul Jackson <pj@sgi.com> Acked-by: Randy Dunlap <rdunlap@xenotime.net> Cc: Alan Cox <alan@lxorguk.ukuu.org.uk> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
* [PATCH] Discuss a couple common errors in kernel-doc usage.Robert P. J. Day2007-02-111-4/+33
| | | | | | | | | Explain a couple of the most common errors in kernel-doc usage. Signed-off-by: Robert P. J. Day <rpjday@mindspring.com> Acked-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
* [PATCH] kernel-doc: allow a little whitespaceRandy Dunlap2007-02-111-1/+1
| | | | | | | | | | | | | In kernel-doc syntax, be a little flexible: allow whitespace between a function parameter name and the colon that must follow it, such as: @pdev : PCI device to unplug (This allows lots of megaraid kernel-doc to work without tons of editing.) Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
* [PATCH] update some docbook commentsRandy Dunlap2006-11-031-1/+1
| | | | | | | | | | | Correct a few comments in kernel-doc Doc and source files. (akpm: note: the patch removes a non-ascii character and might have to be applied by hand..) Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
* [PATCH] Doc/kernel-doc: add more usage infoRandy Dunlap2006-02-011-5/+34
| | | | | | | | | | | | | | - Add info that structs, unions, enums, and typedefs are supported. - Add doc about "private:" and "public:" tags for struct fields. - Fix some typos. - Remove some trailing whitespace. Signed-off-by: Randy Dunlap <rdunlap@xenotime.net> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
* Linux-2.6.12-rc2v2.6.12-rc2Linus Torvalds2005-04-161-0/+150
Initial git repository build. I'm not bothering with the full history, even though we have it. We can create a separate "historical" git archive of that later if we want to, and in the meantime it's about 3.2GB when imported into git - space that would just make the early git days unnecessarily complicated, when we don't have a lot of good infrastructure for it. Let it rip!
generated by cgit v1.2.3 (git 2.25.1) at 2024-11-24 01:00:50 +0000