[prev in list] [next in list] [prev in thread] [next in thread] 

List:       kde-core-devel
Subject:    Kdoc tags - here's some info.
From:       Sirtaj Singh Kang <ssk () physics ! unimelb ! EDU ! AU>
Date:       1999-11-25 0:47:17
[Download RAW message or body]

On Wed, Nov 24, 1999 at 07:54:40PM +0100, Matt Koss wrote:
> 
> I can't find any detailed docs about various kdoc tags.
> 
> Where to look ?

The kdoc web page 

http://www.ph.unimelb.edu.au/~ssk/kde/kdoc/

has a list of all the older tags, but lots of new ones
have appeared recently. I am writing the KDOC User Guide right now (slow
going, I'm still learning docbook), which will have a comprehensive list.
But for now here is an overview.

All places:
All these must appear by themselves on a line.
Note that <string> means a single line of text, while <text> means
multiple lines of text are allowed, and will be ended by another tag
or a blank line.

@author <string>
@version <string>
	I normally use the $Id$ RCS token here.
@internal
@deprecated
@since <string>
@sect <string>
	Section heading, eg "@sect Other sources of information"
@li <text>
	This is a list item and works just like a paragraph.
@image <path>
	You can use a url for the path, but using a plain filename will allow
	the image to be accessible from other formats too.
@see <class::member>,...
	or
@see <namespace::class::nested::member>,...
	or
@see <member>,...
	you get the idea.

@ref is an inline version of @see, so you can use it like this:
This class heavily borrows from @ref KApplication, and 
also from @ref KInstance::Private.

<pre>
	example code etc.
</pre>

Classes only:
@short

Methods:
@param <paramname>	<text>
@returns <text>
@throws <member/class etc like @see>, ...
	@exception or @raises are synonyms for this

@p <paramname>
	An inline tag to highlight the parameter name in text. eg

Remember to pay attention to @p parent, or you'll be in deep doodoo.

Documenting a library:
A doc comment with 
	@libdoc <string - library short description>
will not be associated with any class or member, but with the library
being processed. It will be displayed on the index page of the documentation,
see 

	http://www.ph.unimelb.edu.au/~ssk/kde/srcdoc/kio/

for an example.



-- 
-Taj.

Sirtaj S. Kang       taj@kde.org         ssk@physics.unimelb.edu.au
Univ of Melbourne	The "gui" in "Penguin" is pronounced "K-D-E"

[prev in list] [next in list] [prev in thread] [next in thread]