0
# Output Management
1

2
The output management system provides a flexible framework for writing generated documentation to various targets including file systems, in-memory storage, and custom implementations. This abstraction allows the documentation generation process to work with different output destinations.
3

4
## Core API
5

6
### OutputTool
7

8
Abstract interface that defines the contract for all output implementations.
9

10
```java { .api }
11
public interface OutputTool {
12
    void makeOutputArea(String filename)                                    // Create output directory/area
13
    void writeToOutput(String fileName, String text, String charset)       // Write content to output
14
}
15
```
16

17
The `OutputTool` interface provides the foundation for all output operations:
18
- `makeOutputArea()` - Ensures the output location exists and is ready for writing
19
- `writeToOutput()` - Writes text content to a specific file with specified character encoding
20

21
## Built-in Implementations
22

23
### FileOutputTool
24

25
Concrete implementation for writing documentation to the file system.
26

27
```java { .api }
28
public class FileOutputTool implements OutputTool {
29
    public FileOutputTool()                                                // Default constructor
30
    public void makeOutputArea(String filename)                           // Create directory structure
31
    public void writeToOutput(String fileName, String text, String charset) // Write file to disk
32
}
33
```
34

35
The `FileOutputTool` handles:
36
- Creating directory structures as needed
37
- Writing files with proper character encoding
38
- Managing file system permissions and error handling
39

40
### MockOutputTool
41

42
In-memory implementation primarily used for testing and validation.
43

44
```java { .api }
45
public class MockOutputTool implements OutputTool {
46
    public MockOutputTool()                                                // Default constructor
47
    public void makeOutputArea(String filename)                           // Track output areas
48
    public void writeToOutput(String fileName, String text, String charset) // Store in memory
49
    public boolean isValidOutputArea(String fileName)                      // Check if area exists
50
    public String getText(String fileName)                                 // Retrieve stored text
51
}
52
```
53

54
The `MockOutputTool` provides additional methods for testing:
55
- `isValidOutputArea()` - Verify that an output area was created
56
- `getText()` - Retrieve content that was written to a specific file
57

58
## Usage Examples
59

60
### Basic File System Output
61

62
```java
63
import org.codehaus.groovy.tools.groovydoc.FileOutputTool;
64
import org.codehaus.groovy.tools.groovydoc.GroovyDocTool;
65

66
// Create file system output tool
67
FileOutputTool output = new FileOutputTool();
68

69
// Set up documentation tool
70
String[] sourcePaths = {"src/main/groovy"};
71
GroovyDocTool tool = new GroovyDocTool(sourcePaths);
72
tool.add(Arrays.asList("com/example/MyClass.groovy"));
73

74
// Generate documentation to file system
75
String outputDirectory = "build/docs/groovydoc";
76
tool.renderToOutput(output, outputDirectory);
77

78
// Files will be created in build/docs/groovydoc/
79
// - index.html
80
// - package directories with class documentation
81
// - CSS and JavaScript resources
82
```
83

84
### In-Memory Output for Testing
85

86
```java
87
import org.codehaus.groovy.tools.groovydoc.MockOutputTool;
88
import org.codehaus.groovy.tools.groovydoc.GroovyDocTool;
89

90
// Create mock output tool for testing
91
MockOutputTool mockOutput = new MockOutputTool();
92

93
// Set up documentation tool
94
GroovyDocTool tool = new GroovyDocTool(new String[]{"src/test/groovy"});
95
tool.add(Arrays.asList("TestClass.groovy"));
96

97
// Generate documentation to memory
98
tool.renderToOutput(mockOutput, "test-docs");
99

100
// Verify output was generated
101
if (mockOutput.isValidOutputArea("test-docs/index.html")) {
102
    String indexContent = mockOutput.getText("test-docs/index.html");
103
    System.out.println("Generated index.html:");
104
    System.out.println(indexContent);
105
}
106

107
// Check for specific class documentation
108
String classDocPath = "test-docs/TestClass.html";
109
if (mockOutput.isValidOutputArea(classDocPath)) {
110
    String classContent = mockOutput.getText(classDocPath);
111
    assert classContent.contains("class TestClass");
112
}
113
```
114

115
### Custom Output Implementation
116

117
You can create custom output implementations for specialized requirements:
118

119
```java
120
import org.codehaus.groovy.tools.groovydoc.OutputTool;
121
import java.util.concurrent.ConcurrentHashMap;
122
import java.util.Map;
123

124
// Custom output tool that tracks generation statistics
125
public class StatisticsOutputTool implements OutputTool {
126
    private final OutputTool delegate;
127
    private final Map<String, Integer> fileSizes = new ConcurrentHashMap<>();
128
    private int totalFiles = 0;
129
    
130
    public StatisticsOutputTool(OutputTool delegate) {
131
        this.delegate = delegate;
132
    }
133
    
134
    @Override
135
    public void makeOutputArea(String filename) {
136
        delegate.makeOutputArea(filename);
137
    }
138
    
139
    @Override
140
    public void writeToOutput(String fileName, String text, String charset) {
141
        delegate.writeToOutput(fileName, text, charset);
142
        
143
        // Track statistics
144
        fileSizes.put(fileName, text.length());
145
        totalFiles++;
146
    }
147
    
148
    public int getTotalFiles() { return totalFiles; }
149
    public int getTotalSize() { return fileSizes.values().stream().mapToInt(Integer::intValue).sum(); }
150
    public Map<String, Integer> getFileSizes() { return new HashMap<>(fileSizes); }
151
}
152

153
// Usage
154
FileOutputTool fileOutput = new FileOutputTool();
155
StatisticsOutputTool statsOutput = new StatisticsOutputTool(fileOutput);
156

157
tool.renderToOutput(statsOutput, "docs");
158

159
System.out.println("Generated " + statsOutput.getTotalFiles() + " files");
160
System.out.println("Total size: " + statsOutput.getTotalSize() + " characters");
161
```
162

163
### Output with Error Handling
164

165
```java
166
import org.codehaus.groovy.tools.groovydoc.FileOutputTool;
167
import java.io.IOException;
168

169
// Wrapper to handle output errors gracefully
170
public class SafeOutputTool implements OutputTool {
171
    private final OutputTool delegate;
172
    private final List<String> errors = new ArrayList<>();
173
    
174
    public SafeOutputTool(OutputTool delegate) {
175
        this.delegate = delegate;
176
    }
177
    
178
    @Override
179
    public void makeOutputArea(String filename) {
180
        try {
181
            delegate.makeOutputArea(filename);
182
        } catch (Exception e) {
183
            errors.add("Failed to create output area " + filename + ": " + e.getMessage());
184
        }
185
    }
186
    
187
    @Override
188
    public void writeToOutput(String fileName, String text, String charset) {
189
        try {
190
            delegate.writeToOutput(fileName, text, charset);
191
        } catch (Exception e) {
192
            errors.add("Failed to write " + fileName + ": " + e.getMessage());
193
        }
194
    }
195
    
196
    public List<String> getErrors() { return new ArrayList<>(errors); }
197
    public boolean hasErrors() { return !errors.isEmpty(); }
198
}
199

200
// Usage with error handling
201
SafeOutputTool safeOutput = new SafeOutputTool(new FileOutputTool());
202
tool.renderToOutput(safeOutput, "docs");
203

204
if (safeOutput.hasErrors()) {
205
    System.err.println("Documentation generation completed with errors:");
206
    for (String error : safeOutput.getErrors()) {
207
        System.err.println("  " + error);
208
    }
209
}
210
```
211

212
## Integration with Template Engine
213

214
The output management system works closely with the template engine to write processed templates:
215

216
```java
217
import org.codehaus.groovy.tools.groovydoc.*;
218

219
// The template engine uses the output tool internally
220
ResourceManager resourceManager = new FileSystemResourceManager("templates");
221
GroovyDocTemplateEngine templateEngine = new GroovyDocTemplateEngine(
222
    tool, resourceManager, new String[]{"class.html"}
223
);
224

225
// When renderToOutput() is called, the template engine processes templates
226
// and uses the provided OutputTool to write the results
227
FileOutputTool output = new FileOutputTool();
228
tool.renderToOutput(output, "generated-docs");
229

230
// The process internally does something like:
231
// 1. templateEngine.applyClassTemplates(classDoc) -> returns HTML string
232
// 2. output.writeToOutput("ClassName.html", htmlContent, "UTF-8")
233
```
234

235
## Output Structure
236

237
The typical output structure created by the documentation generation process includes:
238

239
```
240
output-directory/
241
├── index.html                     # Main index page
242
├── overview-frame.html            # Package overview frame
243
├── allclasses-frame.html          # All classes frame
244
├── stylesheet.css                 # Default stylesheet
245
├── package-list                   # Package list for external links
246
└── [package-name]/                # Package directories
247
    ├── package-frame.html         # Package frame
248
    ├── package-summary.html       # Package summary
249
    └── [ClassName].html           # Individual class documentation
250
```
251

252
The exact structure depends on the templates being used and the organization of the source code being documented.