0
# Documentation Model
1

2
The documentation model provides a hierarchical object representation of the parsed Groovy and Java source code documentation. This model allows programmatic access to all documented elements including packages, classes, methods, fields, and their relationships.
3

4
## Model Hierarchy
5

6
The documentation model follows this hierarchy:
7
- `GroovyRootDoc` - Root of all documentation
8
  - `GroovyPackageDoc` - Package-level documentation
9
    - `GroovyClassDoc` - Class/interface documentation
10
      - `GroovyMethodDoc` - Method documentation
11
      - `GroovyFieldDoc` - Field/property documentation
12
      - `GroovyConstructorDoc` - Constructor documentation
13

14
## Core Interfaces
15

16
### GroovyDoc
17

18
Base interface for all documentation elements.
19

20
```java { .api }
21
public interface GroovyDoc {
22
    String commentText()                    // Get processed comment text
23
    String getRawCommentText()             // Get raw comment text
24
    String name()                          // Get element name
25
    String firstSentenceCommentText()      // Get first sentence for summaries
26
    
27
    // Type checking methods
28
    boolean isClass()
29
    boolean isInterface() 
30
    boolean isMethod()
31
    boolean isField()
32
    boolean isConstructor()
33
    boolean isPackage()
34
}
35
```
36

37
### GroovyRootDoc
38

39
Root of the documentation tree, representing the entire documentation set.
40

41
```java { .api }
42
public interface GroovyRootDoc extends GroovyDoc {
43
    GroovyClassDoc[] classes()                                              // Get all classes
44
    GroovyPackageDoc[] specifiedPackages()                                  // Get specified packages
45
    GroovyClassDoc classNamed(GroovyClassDoc groovyClassDoc, String name)   // Find class by name
46
    Map<String, GroovyClassDoc> getVisibleClasses(List importedClassesAndPackages) // Get visible classes
47
}
48
```
49

50
### GroovyPackageDoc
51

52
Represents package-level documentation.
53

54
```java { .api }
55
public interface GroovyPackageDoc extends GroovyDoc {
56
    GroovyClassDoc[] allClasses()                      // Get all classes in package
57
    GroovyClassDoc[] allClasses(boolean filter)       // Get classes with filtering
58
    GroovyClassDoc[] interfaces()                      // Get interfaces
59
    GroovyClassDoc[] ordinaryClasses()                 // Get regular classes
60
    GroovyClassDoc[] enums()                           // Get enums
61
    GroovyClassDoc[] errors()                          // Get errors
62
    GroovyClassDoc[] exceptions()                      // Get exceptions
63
    GroovyClassDoc findClass(String className)         // Find class by name
64
    String summary()                                   // Get package summary
65
    String description()                               // Get package description
66
}
67
```
68

69
### GroovyClassDoc
70

71
Represents class and interface documentation.
72

73
```java { .api }
74
public interface GroovyClassDoc extends GroovyProgramElementDoc {
75
    GroovyMethodDoc[] methods()                    // Get all methods
76
    GroovyMethodDoc[] methods(boolean filter)     // Get methods with filtering
77
    GroovyFieldDoc[] fields()                     // Get all fields
78
    GroovyFieldDoc[] fields(boolean filter)      // Get fields with filtering
79
    GroovyFieldDoc[] properties()                 // Get Groovy properties
80
    GroovyConstructorDoc[] constructors()         // Get constructors
81
    GroovyConstructorDoc[] constructors(boolean filter) // Get constructors with filtering
82
    GroovyClassDoc[] innerClasses()               // Get inner classes
83
    GroovyClassDoc[] innerClasses(boolean filter) // Get inner classes with filtering
84
    GroovyClassDoc superclass()                   // Get superclass
85
    GroovyClassDoc[] interfaces()                 // Get implemented interfaces
86
    
87
    // Class characteristics
88
    boolean isAbstract()
89
    boolean isSerializable()
90
    boolean isEnum()
91
    boolean isException()
92
    boolean isError()
93
    boolean isOrdinaryClass()
94
}
95
```
96

97
## Program Element Base Interfaces
98

99
### GroovyProgramElementDoc
100

101
Base interface for documented program elements (classes, methods, fields).
102

103
```java { .api }
104
public interface GroovyProgramElementDoc extends GroovyDoc {
105
    GroovyAnnotationRef[] annotations()        // Get annotations
106
    GroovyClassDoc containingClass()           // Get containing class
107
    GroovyPackageDoc containingPackage()       // Get containing package
108
    String qualifiedName()                     // Get fully qualified name
109
    String modifiers()                         // Get modifier string
110
    
111
    // Visibility and modifier checks
112
    boolean isPublic()
113
    boolean isPrivate()
114
    boolean isProtected()
115
    boolean isPackagePrivate()
116
    boolean isStatic()
117
    boolean isFinal()
118
}
119
```
120

121
### GroovyMemberDoc
122

123
Base interface for class members.
124

125
```java { .api }
126
public interface GroovyMemberDoc extends GroovyProgramElementDoc {
127
    boolean isSynthetic()    // Check if compiler-generated
128
}
129
```
130

131
### GroovyExecutableMemberDoc
132

133
Base interface for executable members (methods and constructors).
134

135
```java { .api }
136
public interface GroovyExecutableMemberDoc extends GroovyMemberDoc {
137
    GroovyParameter[] parameters()       // Get parameters
138
    String signature()                   // Get method signature
139
    String flatSignature()              // Get flattened signature
140
    GroovyClassDoc[] thrownExceptions()  // Get thrown exceptions
141
    
142
    // Method characteristics
143
    boolean isNative()
144
    boolean isSynchronized()
145
    boolean isVarArgs()
146
}
147
```
148

149
## Member Documentation Interfaces
150

151
### GroovyMethodDoc
152

153
Represents method documentation.
154

155
```java { .api }
156
public interface GroovyMethodDoc extends GroovyExecutableMemberDoc {
157
    GroovyType returnType()                      // Get return type
158
    boolean isAbstract()                         // Check if abstract
159
    GroovyClassDoc overriddenClass()             // Get overridden class
160
    GroovyMethodDoc overriddenMethod()           // Get overridden method
161
    GroovyType overriddenType()                  // Get overridden type
162
    boolean overrides(GroovyMethodDoc method)    // Check if overrides another method
163
}
164
```
165

166
### GroovyConstructorDoc
167

168
Represents constructor documentation.
169

170
```java { .api }
171
public interface GroovyConstructorDoc extends GroovyExecutableMemberDoc {
172
    // Inherits all methods from GroovyExecutableMemberDoc
173
    // No additional methods specific to constructors
174
}
175
```
176

177
### GroovyFieldDoc
178

179
Represents field and property documentation.
180

181
```java { .api }
182
public interface GroovyFieldDoc extends GroovyMemberDoc {
183
    GroovyType type()                      // Get field type
184
    Object constantValue()                 // Get constant value if applicable
185
    String constantValueExpression()       // Get constant value expression
186
    
187
    // Field characteristics
188
    boolean isTransient()
189
    boolean isVolatile() 
190
}
191
```
192

193
## Supporting Type Interfaces
194

195
### GroovyType
196

197
Represents type information for parameters, return values, and fields.
198

199
```java { .api }
200
public interface GroovyType {
201
    String qualifiedTypeName()    // Get fully qualified type name
202
    String simpleTypeName()       // Get simple type name
203
    String typeName()             // Get type name
204
    boolean isPrimitive()         // Check if primitive type
205
}
206
```
207

208
### GroovyParameter
209

210
Represents method and constructor parameters.
211

212
```java { .api }
213
public interface GroovyParameter {
214
    String name()                         // Get parameter name
215
    GroovyType type()                     // Get parameter type
216
    String typeName()                     // Get type name
217
    String defaultValue()                 // Get default value if applicable
218
    GroovyAnnotationRef[] annotations()   // Get parameter annotations
219
}
220
```
221

222
### GroovyAnnotationRef
223

224
Represents annotation usage on program elements.
225

226
```java { .api }
227
public interface GroovyAnnotationRef {
228
    GroovyClassDoc type()       // Get annotation type
229
    String name()               // Get annotation name
230
    String description()        // Get annotation description
231
}
232
```
233

234
### GroovyTag
235

236
Represents documentation tags like @param, @return, @see, etc.
237

238
```java { .api }
239
public interface GroovyTag {
240
    String name()        // Get tag name (e.g., "param", "return")
241
    String param()       // Get tag parameter (for @param tags)
242
    String text()        // Get tag text content
243
}
244
```
245

246
## Usage Examples
247

248
### Navigating the Documentation Model
249

250
```java
251
import org.codehaus.groovy.groovydoc.*;
252

253
// Get the root documentation
254
GroovyRootDoc rootDoc = tool.getRootDoc();
255

256
// Iterate through all packages
257
GroovyPackageDoc[] packages = rootDoc.specifiedPackages();
258
for (GroovyPackageDoc pkg : packages) {
259
    System.out.println("Package: " + pkg.name());
260
    
261
    // Get all classes in the package
262
    GroovyClassDoc[] classes = pkg.allClasses();
263
    for (GroovyClassDoc clazz : classes) {
264
        System.out.println("  Class: " + clazz.qualifiedName());
265
        
266
        // Check class characteristics
267
        if (clazz.isInterface()) {
268
            System.out.println("    Type: Interface");
269
        } else if (clazz.isEnum()) {
270
            System.out.println("    Type: Enum");
271
        } else {
272
            System.out.println("    Type: Class");
273
        }
274
        
275
        // Get superclass and interfaces
276
        GroovyClassDoc superclass = clazz.superclass();
277
        if (superclass != null) {
278
            System.out.println("    Extends: " + superclass.qualifiedName());
279
        }
280
        
281
        GroovyClassDoc[] interfaces = clazz.interfaces();
282
        for (GroovyClassDoc iface : interfaces) {
283
            System.out.println("    Implements: " + iface.qualifiedName());
284
        }
285
    }
286
}
287
```
288

289
### Examining Methods and Parameters
290

291
```java
292
// Get a specific class
293
GroovyClassDoc classDoc = rootDoc.classNamed(null, "com.example.MyClass");
294

295
// Examine all methods
296
GroovyMethodDoc[] methods = classDoc.methods();
297
for (GroovyMethodDoc method : methods) {
298
    System.out.println("Method: " + method.name());
299
    System.out.println("  Signature: " + method.signature());
300
    System.out.println("  Return type: " + method.returnType().typeName());
301
    
302
    // Check modifiers
303
    if (method.isPublic()) System.out.println("  Visibility: public");
304
    if (method.isStatic()) System.out.println("  Static: yes");
305
    if (method.isAbstract()) System.out.println("  Abstract: yes");
306
    
307
    // Examine parameters
308
    GroovyParameter[] params = method.parameters();
309
    for (GroovyParameter param : params) {
310
        System.out.println("  Parameter: " + param.name() + 
311
                         " : " + param.type().typeName());
312
        
313
        // Check for default value
314
        String defaultValue = param.defaultValue();
315
        if (defaultValue != null) {
316
            System.out.println("    Default: " + defaultValue);
317
        }
318
    }
319
    
320
    // Check for thrown exceptions
321
    GroovyClassDoc[] exceptions = method.thrownExceptions();
322
    for (GroovyClassDoc exception : exceptions) {
323
        System.out.println("  Throws: " + exception.qualifiedName());
324
    }
325
}
326
```
327

328
### Working with Fields and Properties
329

330
```java
331
// Examine fields
332
GroovyFieldDoc[] fields = classDoc.fields();
333
for (GroovyFieldDoc field : fields) {
334
    System.out.println("Field: " + field.name());
335
    System.out.println("  Type: " + field.type().typeName());
336
    System.out.println("  Modifiers: " + field.modifiers());
337
    
338
    // Check if it's a constant
339
    Object constantValue = field.constantValue();
340
    if (constantValue != null) {
341
        System.out.println("  Constant value: " + constantValue);
342
    }
343
}
344

345
// Examine Groovy properties (separate from fields)
346
GroovyFieldDoc[] properties = classDoc.properties();
347
for (GroovyFieldDoc property : properties) {
348
    System.out.println("Property: " + property.name());
349
    System.out.println("  Type: " + property.type().typeName());
350
}
351
```
352

353
### Accessing Documentation Comments
354

355
```java
356
// Get comment text from any documentation element
357
System.out.println("Class comment: " + classDoc.commentText());
358
System.out.println("First sentence: " + classDoc.firstSentenceCommentText());
359
System.out.println("Raw comment: " + classDoc.getRawCommentText());
360

361
// Method comments
362
for (GroovyMethodDoc method : classDoc.methods()) {
363
    System.out.println("Method " + method.name() + " comment: " + 
364
                      method.commentText());
365
}
366
```