Class: Sprout::AsDocTask

Inherits:
ToolTask
  • Object
show all
Defined in:
lib/sprout/tasks/asdoc_task.rb,
lib/sprout/tasks/asdoc_documentation.rb

Overview

The AsDoc Task provides Rake support for the asdoc documentation engine. If a MXMLCTask or COMPCTask are found as prerequisites to the AsDoc task, AsDoc will inherit the source_path and library_path from those tasks. You can also configure AsDoc normally if you wish.

This configuration might look something like this:

# Create a remote library dependency on the corelib swc.
library :corelib

# Alias the compilation task with one that is easier to type
# task :compile => 'SomeProject.swf'

AsDoc tasks can be created and configured directly like any other rake task.

# Create a simple, standard asdoc task
asdoc :doc do |t|
  t.source_path               << 'src'
  t.library_path              << 'lib/corelib.swc'
  t.doc_classes               = 'SomeProject'
  t.main_title                = 'Some Project Title'
  t.footer                    = 'This is the footer for your project docs'
end

# Create an MXMLCTask named for the output file that it creates. This task depends on the
# corelib library and will automatically add the corelib.swc to it's library_path
mxmlc 'bin/SomeProject.swf' => :corelib do |t|
  t.input                     = 'src/SomeProject.as'
  t.default_size              = '800 600'
  t.default_background_color  = "#FFFFFF"
  t.source_path               << 'src'
  t.source_path               << 'lib/asunit'
  t.source_path               << 'test'
end

desc "Generate documentation"
asdoc :doc => 'bin/SomeProject.swf'

This configuration will generate documentation in the relative path, ‘doc’, but only if The contents of the documentation directory are older than the sources referenced by the compiler.

For more information about using the asdoc command line compiler, check livedocs at: livedocs.adobe.com/flex/201/html/wwhelp/wwhimpl/common/html/wwhelp.htm?context=LiveDocs_Book_Parts&file=asdoc_127_1.html

Instance Method Summary collapse

Instance Method Details

#actionscript_file_encoding=(string) ⇒ Object

Sets the file encoding for ActionScript files. For more information see: livedocs.adobe.com/flex/2/docs/00001503.html#149244



4
5
6
 
# File 'lib/sprout/tasks/asdoc_documentation.rb', line 4

def actionscript_file_encoding=(string)
  @actionscript_file_encoding = string
end

#benchmark=(boolean) ⇒ Object

Prints detailed compile times to the standard output. The default value is true.



9
10
11
 
# File 'lib/sprout/tasks/asdoc_documentation.rb', line 9

def benchmark=(boolean)
  @benchmark = boolean
end

#define ⇒ Object

:nodoc:



247
248
249
250
251
252
253
 
# File 'lib/sprout/tasks/asdoc_task.rb', line 247

def define # :nodoc:
  apply_exclusions_from_expression unless @exclude_expressions.nil?

  super
  validate_templates
  CLEAN.add(output)
end

#doc_classes=(strings) ⇒ Object

A list of classes to document. These classes must be in the source path. This is the default option.

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 (livedocs.adobe.com/flex/201/html/compilers_123_31.html#162910).



16
17
18
 
# File 'lib/sprout/tasks/asdoc_documentation.rb', line 16

def doc_classes=(strings)
  @doc_classes = strings
end

#doc_namespaces=(strings) ⇒ Object

A list of URIs whose classes should be documented. The classes must be in the source path.

You must include a URI and the location of the manifest file that defines the contents of this namespace.

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. (livedocs.adobe.com/flex/201/html/compilers_123_31.html#162910)



25
26
27
 
# File 'lib/sprout/tasks/asdoc_documentation.rb', line 25

def doc_namespaces=(strings)
  @doc_namespaces = strings
end

#doc_sources=(paths) ⇒ Object

A list of files that should be documented. If a directory name is in the list, it is recursively searched.

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 (livedocs.adobe.com/flex/201/html/compilers_123_31.html#162910).



32
33
34
 
# File 'lib/sprout/tasks/asdoc_documentation.rb', line 32

def doc_sources=(paths)
  @doc_sources = paths
end

#examples_path=(paths) ⇒ Object

A collection of paths that asdoc will use to look for example files that were included using @includeExample.

This is an undocumented feature, but does seem to work.

More info: bugs.adobe.com/jira/browse/FLEXDOCS-476



42
43
44
 
# File 'lib/sprout/tasks/asdoc_documentation.rb', line 42

def examples_path=(paths)
  @examples_path = paths
end

#exclude_classes=(strings) ⇒ Object

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.



47
48
49
 
# File 'lib/sprout/tasks/asdoc_documentation.rb', line 47

def exclude_classes=(strings)
  @exclude_classes = strings
end

#exclude_dependencies=(boolean) ⇒ Object

Whether all dependencies found by the compiler are documented. If true, the dependencies of the input classes are not documented.

The default value is false.



54
55
56
 
# File 'lib/sprout/tasks/asdoc_documentation.rb', line 54

def exclude_dependencies=(boolean)
  @exclude_dependencies = boolean
end

#exclude_expressions ⇒ Object 



243
244
245
 
# File 'lib/sprout/tasks/asdoc_task.rb', line 243

def exclude_expressions
  @exclude_expressions ||= []
end

#footer=(string) ⇒ Object

The text that appears at the bottom of the HTML pages in the output documentation.



59
60
61
 
# File 'lib/sprout/tasks/asdoc_documentation.rb', line 59

def footer=(string)
  @footer = string
end

#initialize_task ⇒ Object 



51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
 
# File 'lib/sprout/tasks/asdoc_task.rb', line 51

def initialize_task
  super
  @default_gem_name = 'sprout-flex3sdk-tool'
  @default_gem_path = 'bin/asdoc'

  add_param(:actionscript_file_encoding, :string) do |p|
    p.description = "Sets the file encoding for ActionScript files. For more information see: http://livedocs.adobe.com/flex/2/docs/00001503.html#149244"
  end

  add_param(:benchmark, :boolean) do |p|
    p.value = true
    p.show_on_false = true
    p.description = "Prints detailed compile times to the standard output. The default value is true."
  end

  add_param(:doc_classes, :strings) do |p|
    p.description =<<EOF
A list of classes to document. These classes must be in the source path. This is the default option.

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 (http://livedocs.adobe.com/flex/201/html/compilers_123_31.html#162910).
EOF
  end

  add_param(:doc_namespaces, :strings) do |p|
    p.description =<<EOF
A list of URIs whose classes should be documented. The classes must be in the source path.

You must include a URI and the location of the manifest file that defines the contents of this namespace.

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. (http://livedocs.adobe.com/flex/201/html/compilers_123_31.html#162910)
EOF
  end

  add_param(:doc_sources, :paths) do |p|
    p.preprocessable = true
    p.description =<<EOF
A list of files that should be documented. If a directory name is in the list, it is recursively searched.

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 (http://livedocs.adobe.com/flex/201/html/compilers_123_31.html#162910).
EOF
  end
  
  add_param(:examples_path, :paths) do |p|
    p.description =<<EOF
A collection of paths that asdoc will use to look for example files that were included using @includeExample.

This is an undocumented feature, but does seem to work.

More info:
http://bugs.adobe.com/jira/browse/FLEXDOCS-476
EOF
  end

  add_param(:exclude_classes, :strings) do |p|
    p.delimiter = '='
    p.description =<<EOF
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.
EOF
  end

  add_param(:exclude_dependencies, :boolean) do |p|
    p.description =<<EOF
Whether all dependencies found by the compiler are documented. If true, the dependencies of the input classes are not documented.

The default value is false.
EOF
  end

  add_param(:footer, :string) do |p|
    p.description =<<EOF
The text that appears at the bottom of the HTML pages in the output documentation.
EOF
  end

  add_param(:left_frameset_width, :number) do |p|
    p.description =<<EOF
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.

The default value is 210 pixels.
EOF
  end

  add_param(:library_path, :files) do |p|
    p.description =<<EOF
Links SWC files to the resulting application SWF file. The compiler only links in those classes for the SWC file that are required.

The default value of the library-path option includes all SWC files in the libs directory and the current locale. These are required.

To point to individual classes or packages rather than entire SWC files, use the source-path option.

If you set the value of the library-path as an option of the command-line compiler, you must also explicitly add the framework.swc and locale SWC files. Your new entry is not appended to the library-path but replaces it.

You can use the += operator to append the new argument to the list of existing SWC files.

In a configuration file, you can set the append attribute of the library-path tag to true to indicate that the values should be appended to the library path rather than replace it.
EOF
  end

  add_param(:load_config, :file) do |p|
    p.description =<<EOF
Specifies the location of the configuration file that defines compiler options.

If you specify a configuration file, you can override individual options by setting them on the command line.

All relative paths in the configuration file are relative to the location of the configuration file itself.

Use the += operator to chain this configuration file to other configuration files.

For more information on using configuration files to provide options to the command-line compilers, see About configuration files (http://livedocs.adobe.com/flex/2/docs/00001490.html#138195).
EOF
  end

  add_param(:main_title, :string) do |p|
    p.description =<<EOF
The text that appears at the top of the HTML pages in the output documentation.

The default value is "API Documentation".
EOF
  end

  add_param(:namespace, :string) do |p|
    p.description =<<EOF
Not sure about this option, it was in the CLI help, but not documented on the Adobe site
EOF
  end

  add_param(:output, :path) do |p|
    p.value = 'doc'
    p.description =<<EOF
The output directory for the generated documentation. The default value is "doc".
EOF
  end

  add_param(:package, :string) do |p|
    p.description =<<EOF
The descriptions to use when describing a package in the documentation. You can specify more than one package option.

The following example adds two package descriptions to the output:
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"
EOF
  end

  add_param(:source_path, :paths) do |p|
    p.preprocessable = true
    p.description =<<EOF
Adds directories or files to the source path. The Flex compiler searches directories in the source path for MXML or AS source files that are used in your Flex applications and includes those that are required at compile time.

You can use wildcards to include all files and subdirectories of a directory.

To link an entire library SWC file and not individual classes or directories, use the library-path option.

The source path is also used as the search path for the component compiler's include-classes and include-resource-bundles options.

You can also use the += operator to append the new argument to the list of existing source path entries.
EOF
  end

  add_param(:strict, :boolean) do |p|
    p.value = true
    p.show_on_false = true
    p.description =<<EOF
Prints undefined property and function calls; also performs compile-time type checking on assignments and options supplied to method calls.

The default value is true.

For more information about viewing warnings and errors, see Viewing warnings and errors (http://livedocs.adobe.com/flex/2/docs/00001517.html#182413).
EOF
  end

  add_param(:templates_path, :paths) do |p|
    p.description =<<EOF
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.
EOF
  end

  add_param(:warnings, :boolean) do |p|
    p.description =<<EOF
Enables all warnings. Set to false to disable all warnings. This option overrides the warn-warning_type options.

The default value is true.
EOF
  end

  add_param(:window_title, :string) do |p|
    p.description =<<EOF
The text that appears in the browser window in the output documentation.

The default value is "API Documentation".
EOF
  end
end

#left_frameset_width=(number) ⇒ Object

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.

The default value is 210 pixels.



66
67
68
 
# File 'lib/sprout/tasks/asdoc_documentation.rb', line 66

def left_frameset_width=(number)
  @left_frameset_width = number
end

#library_path=(files) ⇒ Object

Links SWC files to the resulting application SWF file. The compiler only links in those classes for the SWC file that are required.

The default value of the library-path option includes all SWC files in the libs directory and the current locale. These are required.

To point to individual classes or packages rather than entire SWC files, use the source-path option.

If you set the value of the library-path as an option of the command-line compiler, you must also explicitly add the framework.swc and locale SWC files. Your new entry is not appended to the library-path but replaces it.

You can use the += operator to append the new argument to the list of existing SWC files.

In a configuration file, you can set the append attribute of the library-path tag to true to indicate that the values should be appended to the library path rather than replace it.



81
82
83
 
# File 'lib/sprout/tasks/asdoc_documentation.rb', line 81

def library_path=(files)
  @library_path = files
end

#load_config=(file) ⇒ Object

Specifies the location of the configuration file that defines compiler options.

If you specify a configuration file, you can override individual options by setting them on the command line.

All relative paths in the configuration file are relative to the location of the configuration file itself.

Use the += operator to chain this configuration file to other configuration files.

For more information on using configuration files to provide options to the command-line compilers, see About configuration files (livedocs.adobe.com/flex/2/docs/00001490.html#138195).



94
95
96
 
# File 'lib/sprout/tasks/asdoc_documentation.rb', line 94

def load_config=(file)
  @load_config = file
end

#main_title=(string) ⇒ Object

The text that appears at the top of the HTML pages in the output documentation.

The default value is “API Documentation”.



101
102
103
 
# File 'lib/sprout/tasks/asdoc_documentation.rb', line 101

def main_title=(string)
  @main_title = string
end

#namespace=(string) ⇒ Object

Not sure about this option, it was in the CLI help, but not documented on the Adobe site



106
107
108
 
# File 'lib/sprout/tasks/asdoc_documentation.rb', line 106

def namespace=(string)
  @namespace = string
end

#output=(path) ⇒ Object

The output directory for the generated documentation. The default value is “doc”.



111
112
113
 
# File 'lib/sprout/tasks/asdoc_documentation.rb', line 111

def output=(path)
  @output = path
end

#package=(string) ⇒ Object

The descriptions to use when describing a package in the documentation. You can specify more than one package option.

The following example adds two package descriptions to the output: 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”



119
120
121
 
# File 'lib/sprout/tasks/asdoc_documentation.rb', line 119

def package=(string)
  @package = string
end

#prepare ⇒ Object 



255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
 
# File 'lib/sprout/tasks/asdoc_task.rb', line 255

def prepare
  super
  prerequisite = nil
  @prerequisites.each do |req|
    prerequisite = @application[req]
    if(prerequisite.is_a?(MXMLCTask))
      prerequisite.source_path.each do |path|
        doc_sources << path
      end
      prerequisite.library_path.each do |path|
        library_path << path
      end
    end
  end
end

#source_path=(paths) ⇒ Object

Adds directories or files to the source path. The Flex compiler searches directories in the source path for MXML or AS source files that are used in your Flex applications and includes those that are required at compile time.

You can use wildcards to include all files and subdirectories of a directory.

To link an entire library SWC file and not individual classes or directories, use the library-path option.

The source path is also used as the search path for the component compiler’s include-classes and include-resource-bundles options.

You can also use the += operator to append the new argument to the list of existing source path entries.



132
133
134
 
# File 'lib/sprout/tasks/asdoc_documentation.rb', line 132

def source_path=(paths)
  @source_path = paths
end

#strict=(boolean) ⇒ Object

Prints undefined property and function calls; also performs compile-time type checking on assignments and options supplied to method calls.

The default value is true.

For more information about viewing warnings and errors, see Viewing warnings and errors (livedocs.adobe.com/flex/2/docs/00001517.html#182413).



141
142
143
 
# File 'lib/sprout/tasks/asdoc_documentation.rb', line 141

def strict=(boolean)
  @strict = boolean
end

#templates_path=(paths) ⇒ Object

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.



146
147
148
 
# File 'lib/sprout/tasks/asdoc_documentation.rb', line 146

def templates_path=(paths)
  @templates_path = paths
end

#warnings=(boolean) ⇒ Object

Enables all warnings. Set to false to disable all warnings. This option overrides the warn-warning_type options.

The default value is true.



153
154
155
 
# File 'lib/sprout/tasks/asdoc_documentation.rb', line 153

def warnings=(boolean)
  @warnings = boolean
end

#window_title=(string) ⇒ Object

The text that appears in the browser window in the output documentation.

The default value is “API Documentation”.



160
161
162
 
# File 'lib/sprout/tasks/asdoc_documentation.rb', line 160

def window_title=(string)
  @window_title = string
end