Issue #1489000 by jhodgdon: make file names work in @link links
[project/api.git] / README.txt
1
2 API Module
3 Generates and displays API documentation pages.
4
5 GENERAL INFORMATION
6
7 This is an implementation of a subset of the Doxygen documentation generator
8 specification, tuned to produce output that best benefits the Drupal code base.
9 It is designed to assume the code it documents follows Drupal coding
10 conventions, and supports the following Doxygen constructs:
11   @mainpage
12   @file
13   @defgroup
14   @ingroup
15   @addtogroup (as a synonym of @ ingroup)
16   @param
17   @return
18   @link
19   @see
20   @{
21   @}
22
23
24 In addition to Doxygen syntax requirements, the following restrictions are made
25 on the code format. These are all Drupal coding conventions (see
26 http://drupal.org/node/1354 for more details and suggestions).
27
28 All documentation blocks must use the syntax:
29
30 /**
31  * Documentation here.
32  */
33
34 The leading spaces are required.
35
36 When documenting a function, the documentation block must immediately precede
37 the function it documents, with no intervening blank lines.
38
39 There may be no intervening spaces between a function name and the left
40 parenthesis that follows it.
41
42 Functions must be closed by a right curly bracket in the first column. No lines
43 inside a function may have a right curly bracket in the first column.
44
45
46 Besides the Doxygen features that are supported, this module also provides the
47 following features:
48
49 CVS version numbers and dates are parsed from
50 tags and reported.
51
52 Functions may be in multiple groups (Doxygen ignores all but the first
53 group). This allows, for example, theme_menu_tree() to be marked as both
54 "themeable" and part of the "menu system".
55
56 Function calls to PHP library functions are linked to the PHP manual.
57
58 Function calls have tooltips briefly describing the called function.
59
60 Documentation pages have non-volatile, predictable URLs, so links to individual
61 functions will not be invalidated when the number of functions in a document
62 changes.
63
64 INSTALLATION AND SETUP
65
66 See http://drupal.org/node/425944 for information on how to install and set up
67 this module.