Valadoc - Documentation tool for the vala project

Contents

Valadoc - Documentation tool for the vala project

Introduction

Valadoc is a documentation generator for generating API documentation from Vala source code based on libvala.

Documentation Comments

Structure

    /**
     * A single \
     * line.
     */

    /**
       A single line.
     */

    /** A single line. */

The first paragraph is interpreted as a brief description.

Unlike javadoc we like to avoid HTML-Code in our documentation comments to make it easer to support different output formats like XML, pdf and odf.

Wiki Tags

Bold
Tag	Context	Childs
++text++	short descriptions, description, package documenatation, taglets	italic, bold, underline, link, inline taglet

  ++bold++

'bold'

Italic
Tag	Context	Childs
//text//	short descriptions, description, package documenatation, taglets	italic, bold, underline, link, inline taglet

  //italic//

italic

Underline
Tag	Context	Childs
__text__	short descriptions, description, package documenatation, taglets	italic, bold, underline, link, inline taglet

 __underline__

underline

Image
Tag	Context	Children
{{path}}, {{path\|alt}}	description, package documentation	-

   {{http://library.gnome.org/skin/admon-warning.png}}

Link
Tag	Context	Children
[[link]], [[link\|desc]]	short descriptions, description, package documenatation, taglets	-

  [[http://www.gnome.org|Gnome]]

Gnome

Align Right
Tag	Context	Childs
))	description, package documentation	inline taglet, link, image, bold, italic, underline

  )) Text

Text

Align Center
Tag	Context	Childs
)(	description, package documentation	inline taglet, link, image, bold, italic, underline

   )( Text

Text

Sorted List
Tag	Context	Childs
#text	description, package documentation	inline taglet, image, bold, italic, underline

 # Level 1
 # Level 1
   # Level 1
   # Level 1

Level 1
Level 1
1. Level 1
2. Level 1

List
Tag	Context	Childs
-text	description, package documentation	inline taglet, image, bold, italic, underline

 - Level 1
 - Level 1
   - Level 1
   - Level 1

Level 1
Level 1
- Level 1
- Level 1

Source
Tag	Context	Childs
{{{Source}}}	description, package documentation	-

   { {{
     Source Code
   }} }

   Source Code

Warning
Tag	Context	Childs
[[warning: text]]	description, package documentation	italic, bold, underline, inline taglet, image

  [[warning:
      Warning.
  ]]

Warning.

Headline
Tag	Context	Childs
== Headline	package documentation	-

 == Headline Lvl1
 === Headline Lvl2
 ==== Headline Lvl3

Table
Tag	Context	Childs
\|\|cell\|\|, \|\|<cellattributes>cell\|\|	package documented, description	#Child#
Attributes
\|nr	column span
-nr	row span
#hex	background color
)(	align center
))	align right
v	vertical align bottom
^	vertical align top

   ||<-3)(> Headline ||
   || - || - || - ||

Headline
-	-	-

Valadoc Tags

Tag & Parameters	Description	Context
@see [symbol]	Creates a link to another part of the documentation	all
@return [description]	-	methods, signals, delegates
@throws [exception, description]	-	methods, signals, delegates
@since [version]	-	all
@param [name, description]	-	methods, signals, delegates
{ @link [symbol] }	Creates a link to another part of the documentation	all
{ @inheritDoc }	-	overwritten methods

Example

   valadoc -o docu src/test.vala --force --wiki documentation/

Roadmap

New Tags: @deprecated [Version, Description], @since [Version]
gtk-doc-Translation (C-Code+gtk-doc comments)
Vala-Attributes

Download

Development is going on git://git.gnome.org/valadoc and can be viewed here.

 git clone git://git.gnome.org/valadoc

Requirements

Contact

Florian Brosch <flo dot brosch at gmail dot com>
https://bugs.launchpad.net/valadoc

live.gnome.org