1 /*
2 * Copyright (c) 2006 Israfil Consulting Services Corporation
3 * Copyright (c) 2006 Christian Edward Gruber
4 * All Rights Reserved
5 *
6 * This software is licensed under the Berkeley Standard Distribution license,
7 * (BSD license), as defined below:
8 *
9 * Redistribution and use in source and binary forms, with or without
10 * modification, are permitted provided that the following conditions are met:
11 *
12 * 1. Redistributions of source code must retain the above copyright notice, this
13 * list of conditions and the following disclaimer.
14 * 2. Redistributions in binary form must reproduce the above copyright notice,
15 * this list of conditions and the following disclaimer in the documentation
16 * and/or other materials provided with the distribution.
17 * 3. Neither the name of Israfil Consulting Services nor the names of its contributors
18 * may be used to endorse or promote products derived from this software without
19 * specific prior written permission.
20 *
21 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
22 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
23 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
24 * IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
25 * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
26 * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
27 * OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
28 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
29 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
30 * OF SUCH DAMAGE.
31 *
32 * $Id: CompCompilerMojo.java 573 2007-12-20 03:12:19Z christianedwardgruber $
33 */
34 package net.israfil.mojo.flex2;
35
36 import java.io.File;
37 import java.io.IOException;
38 import java.util.List;
39 import java.util.Locale;
40
41 import javax.swing.Renderer;
42
43 import org.apache.maven.plugin.MojoExecutionException;
44 import org.apache.maven.plugin.MojoFailureException;
45 import org.apache.maven.reporting.MavenReport;
46 import org.apache.maven.reporting.MavenReportException;
47 import org.codehaus.doxia.sink.Sink;
48 import org.codehaus.plexus.util.StringUtils;
49
50
51 /***
52 * API Document generator for Actionscript 3 code.
53 *
54 * @author <a href="cgruber@israfil.net">Christian Edward Gruber</a>
55 * @version $Id: CompCompilerMojo.java 573 2007-12-20 03:12:19Z christianedwardgruber $
56 *
57 * @goal asdoc
58 * @requiresDependencyResolution
59 * @requiresProject
60 */
61 public class ASDocMojo extends AbstractFlexMojo implements MavenReport {
62
63 /***
64 * Generates the site report
65 *
66 * @component
67 */
68 private Renderer siteRenderer;
69
70 /***
71 * Specifies the destination directory where javadoc saves the generated HTML files.
72 *
73 * @parameter expression="${project.reporting.outputDirectory}/apidocs"
74 * @required
75 */
76 private File reportOutputDirectory;
77
78 /***
79 * The name of the destination directory.
80 *
81 * @parameter expression="${destDir}" default-value="apidocs"
82 */
83 private String destDir;
84
85 /***
86 * The location of the asdoc templates to be used in generating documentation
87 *
88 * @parameter expression="${asdoc.templates}" default-value="${flex.home}/asdoc/templates"
89 * @required
90 */
91 protected File asdocTemplates;
92
93 /***
94 * Report name
95 *
96 * @parameter default-value="ASDocs"
97 * @required
98 */
99 private String name;
100
101 /***
102 * Report description
103 *
104 * @parameter default-value="ASDoc Actionscript API Documentation"
105 * @required
106 */
107 private String description;
108
109 public boolean canGenerateReport() {
110 // TODO: Make this do aggregate reports of all sub-projects.
111 // See: JavadocReport
112 return true;
113 }
114
115 public String getCategoryName() {
116 return CATEGORY_PROJECT_REPORTS;
117 }
118
119 public String getDescription( Locale locale ) {
120 return description;
121 }
122
123 public String getName(Locale locale) {
124 return name;
125 }
126
127 public String getOutputName() {
128 return destDir + "/index";
129 }
130
131 public File getReportOutputDirectory() {
132 return reportOutputDirectory;
133 }
134
135 public boolean isExternalReport() {
136 return true;
137 }
138
139 /***
140 * Method to set the directory where the generated reports will be put. As
141 * with Javadoc, make sure that the resulting path ends with ${destdir}
142 *
143 * @param reportOutputDirectory the directory file to be set
144 */
145 public void setReportOutputDirectory( File reportOutputDirectory ) {
146 if ( ( reportOutputDirectory != null ) && ( !reportOutputDirectory.getAbsolutePath().endsWith( destDir ) ) ){
147 this.reportOutputDirectory = new File( reportOutputDirectory, destDir );
148 } else {
149 this.reportOutputDirectory = reportOutputDirectory;
150 }
151 }
152
153 public void generate(Sink sink, Locale locale) throws MavenReportException {
154 // TODO Auto-generated method stub
155
156 }
157
158
159 protected String getCompilerClass() { return "flex2.tools.ASDoc"; }
160
161 protected String getExecutableJar() { return "asdoc.jar"; }
162
163 protected File getOutputFile() {
164 return getFile(outputDirectory, finalName, "asdoc");
165
166 }
167
168 protected String getFileExtension() {
169 // TODO Auto-generated method stub
170 return null;
171 }
172
173
174 protected List prepareParameters() throws MojoFailureException, MojoExecutionException {
175 List parameters = super.prepareParameters();
176
177 parameters.add( "-doc-sources" );
178
179 try {
180 parameters.add( source.getCanonicalPath());
181 } catch (IOException e) {
182 throw new MojoExecutionException("Source path doesn't exist.", e);
183 }
184
185 parameters.add( "-templates-path" );
186
187 try {
188 parameters.add( asdocTemplates.getCanonicalPath());
189 } catch (IOException e) {
190 throw new MojoExecutionException("Templates path doesn't exist.", e);
191 }
192
193 // define output folder.
194 parameters.add("-output");
195 File asdocOutput = reportOutputDirectory;
196 try {
197 parameters.add(asdocOutput.getCanonicalPath());
198 } catch (IOException e) {
199 throw new MojoExecutionException("Exception attempting to set output file: " + asdocOutput.getPath(), e);
200 }
201
202 return parameters;
203 }
204
205 protected void postProcess() {
206
207
208
209 }
210
211
212
213 /*
214 asdoc -source-path C:\flex\frameworks\source
215 -doc-classes mx.controls.Button
216 -main-title "Flex API Documentation"
217 -window-title "Flex API Documentation"
218 -output flex-framework-asdoc
219
220 asdoc -source-path . -doc-classes comps.GraphingWidget comps.GraphingWidgetTwo
221
222 asdoc -source-path C:\flex\class_dir -doc-classes comps.GraphingWidget comps.GraphingWidgetTwo
223
224 asdoc -source-path . -doc-sources .
225
226 asdoc -source-path frameworks
227 -namespace http://framework frameworks/core-framework-manifest.xml
228 -doc-namespaces http://framework
229
230 asdoc -source-path . -doc-sources . -exclude-classes comps.PageWidget comps.ScreenWidget
231
232 Option
233 Description
234 -doc-classes path-element [...]
235 A list of classes to document. These classes must be in the source path. This is the default option.
236 This option works the same way as does the -include-classes option for the compc component compiler. For more information, see Using the component compiler.
237 -doc-namespaces uri manifest
238 A list of URIs whose classes should be documented. The classes must be in the source path.
239 You must include a URI and the location of the manifest file that defines the contents of this namespace.
240 This option works the same way as does the -include-namespaces option for the compc component compiler. For more information, see Using the component compiler.
241 -doc-sources path-element [...]
242 A list of files that should be documented. If a directory name is in the list, it is recursively searched.
243 This option works the same way as does the -include-sources option for the compc component compiler. For more information, see Using the component compiler.
244 -exclude-classes string
245 A list of classes that should not be documented. You must specify individual class names. Alternatively, if the ASDoc comment for the class contains the @private tag, is not documented.
246 -exclude-dependencies true|false
247 Whether all dependencies found by the compiler are documented. If true, the dependencies of the input classes are not documented.
248 The default value is false.
249 -footer string
250 The text that appears at the bottom of the HTML pages in the output documentation.
251 -left-frameset-width int
252 An integer that changes the width of the left frameset of the documentation. You can change this size to accommodate the length of your package names.
253 The default value is 210 pixels.
254 -main-title "string"
255 The text that appears at the top of the HTML pages in the output documentation.
256 The default value is "API Documentation".
257 -output string
258 The output directory for the generated documentation. The default value is "asdoc-output".
259 -package name "description"
260 The descriptions to use when describing a package in the documentation. You can specify more than one package option.
261 The following example adds two package descriptions to the output:
262 asdoc -doc-sources my_dir -output myDoc -package com.my.business "Contains business classes and interfaces" -package com.my.commands "Contains command base classes and interfaces"
263 -templates-path string
264 The path to the ASDoc template directory. The default is the asdoc/templates directory in the ASDoc installation directory. This directory contains all the HTML, CSS, XSL, and image files used for generating the output.
265 -window-title "string"
266 The text that appears in the browser window in the output documentation.
267 The default value is "API Documentation".
268 The asdoc command also recognizes the following options from the compc component compiler:
269
270 -source-path
271 -library-path
272 -namespace
273 -load-config
274 -actionscript-file-encoding
275 -help
276 -advanced
277 -benchmark
278 -strict
279 -warnings
280
281
282 -benchmark
283 -compiler.accessible
284 -compiler.actionscript-file-encoding <string>
285 -compiler.context-root <context-path>
286 -compiler.debug
287 -compiler.external-library-path [path-element] [...]
288 -compiler.fonts.flash-type
289 -compiler.fonts.max-glyphs-per-face <string>
290 -compiler.include-libraries [library] [...]
291 -compiler.incremental
292 -compiler.library-path [path-element] [...]
293 -compiler.locale <string>
294 -compiler.namespaces.namespace <uri> <manifest>
295 -compiler.optimize
296 -compiler.services <filename>
297 -compiler.show-actionscript-warnings
298 -compiler.show-binding-warnings
299 -compiler.show-deprecation-warnings
300 -compiler.show-unused-type-selector-warnings
301 -compiler.source-path [path-element] [...]
302 -compiler.strict
303 -compiler.theme [filename] [...]
304 -compiler.use-resource-bundle-metadata
305 -doc-classes [class] [...]
306 -doc-namespaces [uri] [...]
307 -doc-sources [path-element] [...]
308 -exclude-classes [class] [...]
309 -exclude-dependencies
310 -footer <string>
311 -help [keyword] [...]
312 -left-frameset-width <int>
313 -licenses.license <product> <serial-number>
314 -load-config <filename>
315 -main-title <string>
316 -metadata.contributor <name>
317 -metadata.creator <name>
318 -metadata.date <text>
319 -metadata.description <text>
320 -metadata.language <code>
321 -metadata.localized-description <text> <lang>
322 -metadata.localized-title <title> <lang>
323 -metadata.publisher <name>
324 -metadata.title <text>
325 -output <filename>
326 -packages.package <string> <string>
327 -runtime-shared-libraries [url] [...]
328 -templates-path <string>
329 -use-network
330 -version
331 -window-title <string>
332
333 */
334
335
336 }