0
# Documentation Generation
1
2
The documentation generation capability provides the core functionality for creating Groovy documentation from source code. This includes parsing source files, extracting documentation comments, and building the documentation model.
3
4
## Core API
5
6
### GroovyDocTool
7
8
The primary class for documentation generation operations.
9
10
```java
11
public class GroovyDocTool
12
```
13
14
#### Constructors
15
16
```java
17
// Basic constructor for simple documentation generation
18
public GroovyDocTool(String[] sourcepaths)
19
20
// Constructor with template support
21
public GroovyDocTool(ResourceManager resourceManager, String[] sourcepaths, String classTemplate)
22
23
// Full constructor with all configuration options
24
public GroovyDocTool(ResourceManager resourceManager, String[] sourcepaths,
25
String[] docTemplates, String[] packageTemplates,
26
String[] classTemplates, List<LinkArgument> links,
27
String javaVersion, Properties properties)
28
```
29
30
#### Key Methods
31
32
```java { .api }
33
// Add source files to be processed
34
public void add(List<String> filenames)
35
36
// Get the complete documentation model
37
public GroovyRootDoc getRootDoc()
38
39
// Generate final documentation output
40
public void renderToOutput(OutputTool output, String destdir)
41
```
42
43
## Usage Examples
44
45
### Basic Documentation Generation
46
47
```java
48
import org.codehaus.groovy.tools.groovydoc.GroovyDocTool;
49
import org.codehaus.groovy.tools.groovydoc.FileOutputTool;
50
import java.util.Arrays;
51
import java.util.List;
52
53
// Set up source paths
54
String[] sourcePaths = {
55
"src/main/groovy",
56
"src/main/java"
57
};
58
59
// Create the documentation tool
60
GroovyDocTool tool = new GroovyDocTool(sourcePaths);
61
62
// Add specific source files
63
List<String> sourceFiles = Arrays.asList(
64
"com/example/GroovyClass.groovy",
65
"com/example/JavaClass.java",
66
"com/example/interfaces/MyInterface.groovy"
67
);
68
tool.add(sourceFiles);
69
70
// Generate documentation
71
FileOutputTool output = new FileOutputTool();
72
tool.renderToOutput(output, "build/docs/groovydoc");
73
```
74
75
### Advanced Configuration
76
77
```java
78
import org.codehaus.groovy.tools.groovydoc.*;
79
import java.util.Properties;
80
import java.util.List;
81
import java.util.Arrays;
82
83
// Set up resource manager for custom templates
84
ResourceManager resourceManager = new FileSystemResourceManager("templates");
85
86
// Configure templates
87
String[] docTemplates = {"overview-frame.html", "allclasses-frame.html"};
88
String[] packageTemplates = {"package-frame.html", "package-summary.html"};
89
String[] classTemplates = {"class.html"};
90
91
// Configure external links
92
List<LinkArgument> links = Arrays.asList(
93
new LinkArgument("http://docs.oracle.com/javase/8/docs/api/", "java.*,javax.*"),
94
new LinkArgument("http://docs.groovy-lang.org/latest/html/api/", "groovy.*")
95
);
96
97
// Set up properties
98
Properties props = new Properties();
99
props.setProperty("windowTitle", "My Project API");
100
props.setProperty("docTitle", "My Project Documentation");
101
102
// Create fully configured tool
103
GroovyDocTool tool = new GroovyDocTool(
104
resourceManager,
105
new String[]{"src/main/groovy", "src/main/java"},
106
docTemplates,
107
packageTemplates,
108
classTemplates,
109
links,
110
"1.8", // Java version
111
props
112
);
113
114
// Add source files and generate
115
tool.add(Arrays.asList("com/example/*.groovy"));
116
tool.renderToOutput(new FileOutputTool(), "docs/api");
117
```
118
119
### Working with the Documentation Model
120
121
```java
122
import org.codehaus.groovy.groovydoc.*;
123
124
// Generate and access the documentation model
125
GroovyDocTool tool = new GroovyDocTool(sourcePaths);
126
tool.add(sourceFiles);
127
128
// Access the root documentation object
129
GroovyRootDoc rootDoc = tool.getRootDoc();
130
131
// Iterate through all documented classes
132
GroovyClassDoc[] allClasses = rootDoc.classes();
133
for (GroovyClassDoc classDoc : allClasses) {
134
System.out.println("Class: " + classDoc.qualifiedName());
135
136
// Access methods
137
GroovyMethodDoc[] methods = classDoc.methods();
138
for (GroovyMethodDoc method : methods) {
139
System.out.println(" Method: " + method.name() + method.signature());
140
}
141
142
// Access fields
143
GroovyFieldDoc[] fields = classDoc.fields();
144
for (GroovyFieldDoc field : fields) {
145
System.out.println(" Field: " + field.name() + " : " + field.type().typeName());
146
}
147
}
148
```
149
150
## Configuration Classes
151
152
### LinkArgument
153
154
Configuration for external documentation links.
155
156
```java { .api }
157
public class LinkArgument {
158
public String getHref() // Get link URL
159
public void setHref(String href) // Set link URL
160
public String getPackages() // Get comma-separated packages
161
public void setPackages(String packages) // Set packages to link
162
}
163
```
164
165
Usage example:
166
167
```java
168
LinkArgument link = new LinkArgument();
169
link.setHref("http://docs.groovy-lang.org/latest/html/api/");
170
link.setPackages("groovy.*,org.codehaus.groovy.*");
171
```
172
173
## Error Handling
174
175
The documentation generation process may encounter various issues with source files or configuration. Errors are typically reported through the logging system and may result in incomplete documentation generation.
176
177
Common issues include:
178
- Invalid source file paths
179
- Syntax errors in source files
180
- Missing template files
181
- I/O errors during output generation
182
183
To monitor for errors, check the logging output during generation:
184
185
```java
186
// The tool uses internal logging - monitor console output for warnings/errors
187
GroovyDocTool tool = new GroovyDocTool(sourcePaths);
188
tool.add(sourceFiles);
189
// Check console for any error messages during processing
190
tool.renderToOutput(output, outputDir);
191
```