Class: ASRake::Asdoc

Inherits:
BaseExecutable show all
Includes:
ASRake, Rake::DSL
Defined in:
lib/asrake/asdoc.rb

Constant Summary collapse

@@compiler_args = 
[
	[:source_path, :dirs],
	[:load_config, :dirs],
	[:library_path, :dirs],
	[:namespace, :string],
	#
	# The output directory for the generated documentation. The default value is "asdoc-output".
	#
	[:output, :dir],
	#
	# When true, retain the intermediate XML files created by the ASDoc tool. The default value is false. 
	#
	[:keep_xml, :bool],
	#
	# When true, configures the ASDoc tool to generate the intermediate XML files only, and not perform
	# the final conversion to HTML. The default value is false. 
	#
	[:skip_xsl, :bool],
	#
	# 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.
	#
	[:exclude_dependencies, :bool],
	#
	# Ignore XHTML errors (such as a missing </p> tag) and produce the ASDoc output.
	# All errors are written to the validation_errors.log file. 
	#
	[:lenient, :bool],
	#
	# 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. 
	#
	[:templates_path, :dir],
	#
	# 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.
	#
	[:doc_classes, :array],
	# 
	# A list of classes not documented. You must specify individual class names.
	# Alternatively, if the ASDoc comment for the class contains the @private tag, is not documented. 
	#
	[:exclude_classes, :array],
	#
	# A list of URIs to document. 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.
	#
	[:doc_namespaces, :array],
	#
	# Specifies the location of the include examples used by the @includeExample tag. This option specifies the
	# root directory. The examples must be located under this directory in subdirectories that correspond to the
	# package name of the class. For example, you specify the examples-path as c:\myExamples. For a class in the
	# package myComp.myClass, the example must be in the directory c:\myExamples\myComp.myClass.
	#
	[:examples_path, :dir],
	#
	# The text that appears at the bottom of the HTML pages in the output documentation.
	#
	[:footer, :string],
	#
	# The text that appears in the browser window in the output documentation.
	# The default value is "API Documentation".
	#
	[:window_title, :string],
	#
	# 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.
	#
	[:left_frameset_width, :string],
	#
	# The text that appears at the top of the HTML pages in the output documentation.
	# The default value is "API Documentation".
	#
	[:main_title, :string],
	#
	# 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 = ASRake::Asdoc.new
	# asdoc.package << 'com.my.business "Contains business classes and interfaces"'
	# asdoc.package << 'com.my.commands "Contains command base classes and interfaces"'
	[:package, :array],
	#
	# Specifies an XML file containing the package descriptions. 
	#
	[:package_description_file, :dir],
	#
	# Disable strict compilation mode. By default, classes that do not define constructors, or contain methods
	# that do not define return values cause compiler failures. If necessary, set strict to false to override
	# this default and continue compilation.
	#
	[:strict, :bool]
]

Instance Attribute Summary collapse

Attributes inherited from BaseExecutable

#output, #output_dir, #output_file

Instance Method Summary collapse

Methods included from ASRake

get_classes

Methods inherited from BaseExecutable

#merge_in, #output_is_dir?, #pathmap, #to_s, #to_str

Constructor Details

#initialize(output) ⇒ Asdoc

Returns a new instance of Asdoc.



118
119
120
121
122
123
124
125
126
127
 
# File 'lib/asrake/asdoc.rb', line 118

def initialize(output)
	super

	# set all defaults
	@@compiler_args.each do |name, type|
		instance_variable_set("@#{name}", []) if type == :array || type == :dirs
	end

	@doc_sources = []
end

Instance Attribute Details

#additional_args ⇒ Object

Returns the value of attribute additional_args.



12
13
14
 
# File 'lib/asrake/asdoc.rb', line 12

def additional_args
  @additional_args
end

#doc_sources ⇒ Object

we have some special handling of this



15
16
17
 
# File 'lib/asrake/asdoc.rb', line 15

def doc_sources
  @doc_sources
end

Instance Method Details

#add(args) ⇒ Object 



129
130
131
132
133
134
135
 
# File 'lib/asrake/asdoc.rb', line 129

def add(args)
	self.source_path << args.source_path
	self.library_path << args.library_path
	self.library_path << args.include_libraries
	self.library_path << args.external_library_path
	args.source_path.each { |p| self.doc_classes << ASRake::get_classes(p) } if args.kind_of? ASRake::Compc
end

#execute(&block) ⇒ Object 



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
 
# File 'lib/asrake/asdoc.rb', line 137

def execute(&block)
	args = ""
	@@compiler_args.each do |name, type|
		arg = name.to_s.gsub('_','-')
		value = instance_variable_get("@#{name}")
		case type
		when :bool
			args << " -#{arg}=#{value}" if value
		when :dirs
			value.flatten!
			value.uniq!
			value = value.map{|s| s.index(' ') != nil ? "\"#{s}\"" : s} if value.length > 1
			args << " -#{arg} #{Path::forward value.join(' ')}" if !value.empty?
		when :dir
			if value != nil
				value = "\"#{value}\"" if value.index(' ') != nil
				args << " -#{arg}=#{Path::forward value}"
			end
		when :array
			value.flatten!
			value.uniq!
			args << " -#{arg} #{value.join(' ')}" if !value.empty?
		when :string
			args << " -#{arg} #{value}" if value != nil
		else
			fail "unknown type #{type}"
		end
	end
	
	# Use doc-sources argument if it has been assigned (duh) or if neither doc-classes or doc-namespaces have
	# been assigned and source-path has
	if !self.doc_sources.empty?
		args << " -doc-sources #{Path::forward doc_sources.join(' ')}"
	elsif !self.source_path.empty? && self.doc_classes.empty? && self.doc_namespaces.empty?
		args << " -doc-sources #{Path::forward source_path.join(' ')}" if !self.source_path.empty?
	end

	args << " #{additional_args}" if self.additional_args != nil
	
	run("#{FlexSDK::asdoc} #{args}", true, &block)
end