version 1, including all changes.
.
| Rev |
Author |
# |
Line |
| 1 |
perry |
1 |
GNOME-DOC |
| |
|
2 |
!!!GNOME-DOC |
| |
|
3 |
NAME |
| |
|
4 |
SYNOPSIS |
| |
|
5 |
DESCRIPTION |
| |
|
6 |
OPTIONS |
| |
|
7 |
FORMAT OF COMMENTS |
| |
|
8 |
AUTHOR |
| |
|
9 |
---- |
| |
|
10 |
!!NAME |
| |
|
11 |
|
| |
|
12 |
|
| |
|
13 |
gnome-doc - Documentation tool for GNOME |
| |
|
14 |
!!SYNOPSIS |
| |
|
15 |
|
| |
|
16 |
|
| |
|
17 |
__gnome-doc__ [[ __-docbook | -html | -text | -man__ ] |
| |
|
18 |
[[ __-function funcname [[ -function funcname ...]__ ] [[ |
| |
|
19 |
__c files__ ] |
| |
|
20 |
!!DESCRIPTION |
| |
|
21 |
|
| |
|
22 |
|
| |
|
23 |
__gnome-doc__ This will read a 'c' file and scan for |
| |
|
24 |
embedded comments in the style of gnome comments (+minor |
| |
|
25 |
extensions - see below). |
| |
|
26 |
|
| |
|
27 |
|
| |
|
28 |
All output goes to stdout, with errors to |
| |
|
29 |
stderr. |
| |
|
30 |
!!OPTIONS |
| |
|
31 |
|
| |
|
32 |
|
| |
|
33 |
__-docbook -html -text -man__ |
| |
|
34 |
|
| |
|
35 |
|
| |
|
36 |
Set output format using one of -docbook -html -text or -man. |
| |
|
37 |
Default is man. |
| |
|
38 |
|
| |
|
39 |
|
| |
|
40 |
__-function__ |
| |
|
41 |
|
| |
|
42 |
|
| |
|
43 |
If set, then only generate documentation for the given |
| |
|
44 |
function(s). All other functions are ignored. |
| |
|
45 |
|
| |
|
46 |
|
| |
|
47 |
__c files__ |
| |
|
48 |
|
| |
|
49 |
|
| |
|
50 |
list of 'c' files to process |
| |
|
51 |
!!FORMAT OF COMMENTS |
| |
|
52 |
|
| |
|
53 |
|
| |
|
54 |
In the following table, |
| |
|
55 |
(...)? signifies optional structure. |
| |
|
56 |
(...)* signifies 0 or more structure elements. |
| |
|
57 |
/** |
| |
|
58 |
* function_name(:)? (- short description)? |
| |
|
59 |
* @parameterx: (description of parameter x)?)* |
| |
|
60 |
(* a blank line)? |
| |
|
61 |
* (Description:)? (Description of function)? |
| |
|
62 |
* (section header: (section description)? )* |
| |
|
63 |
(*)?*/ |
| |
|
64 |
So .. the trivial example would be: |
| |
|
65 |
/** |
| |
|
66 |
* my_function |
| |
|
67 |
**/ |
| |
|
68 |
If the Description: header tag is omitted, then there must be a blank |
| |
|
69 |
line after the last parameter specification. |
| |
|
70 |
e.g. |
| |
|
71 |
/** |
| |
|
72 |
* my_function - does my stuff |
| |
|
73 |
* @my_arg: its mine damnit |
| |
|
74 |
* |
| |
|
75 |
* Does my stuff explained. |
| |
|
76 |
*/ |
| |
|
77 |
or, could also use: |
| |
|
78 |
/** |
| |
|
79 |
* my_function - does my stuff |
| |
|
80 |
* @my_arg: its mine damnit |
| |
|
81 |
* Description: Does my stuff explained. |
| |
|
82 |
*/ |
| |
|
83 |
etc. |
| |
|
84 |
All descriptions can be multiline, apart from the short function |
| |
|
85 |
description. |
| |
|
86 |
All descriptive text is further processed, scanning for the |
| |
|
87 |
following special patterns, which are highlighted appropriately. |
| |
|
88 |
funcname() - function |
| |
|
89 |
$ENVVAR - environmental variable |
| |
|
90 |
struct_name - name of a structure |
| |
|
91 |
@parameter - name of a parameter |
| |
|
92 |
%CONST - name of a constant. |
| |
|
93 |
!!AUTHOR |
| |
|
94 |
|
| |
|
95 |
|
| |
|
96 |
This manual page was written by Christian Marillat |
| |
|
97 |
---- |
