Class Sprout::AsDocTask
In: bundles/as3/lib/sprout/tasks/asdoc_documentation.rb
bundles/as3/lib/sprout/tasks/asdoc_task.rb
Parent: ToolTask

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

Methods

Public Instance methods

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

[Source]

# File bundles/as3/lib/sprout/tasks/asdoc_documentation.rb, line 4
def actionscript_file_encoding=(string)
  @actionscript_file_encoding = string
end

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

[Source]

# File bundles/as3/lib/sprout/tasks/asdoc_documentation.rb, line 9
def benchmark=(boolean)
  @benchmark = boolean
end

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).

[Source]

# File bundles/as3/lib/sprout/tasks/asdoc_documentation.rb, line 16
def doc_classes=(strings)
  @doc_classes = strings
end

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)

[Source]

# File bundles/as3/lib/sprout/tasks/asdoc_documentation.rb, line 25
def doc_namespaces=(strings)
  @doc_namespaces = strings
end

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).

[Source]

# File bundles/as3/lib/sprout/tasks/asdoc_documentation.rb, line 32
def doc_sources=(paths)
  @doc_sources = paths
end

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

[Source]

# File bundles/as3/lib/sprout/tasks/asdoc_documentation.rb, line 42
def examples_path=(paths)
  @examples_path = paths
end

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.

[Source]

# File bundles/as3/lib/sprout/tasks/asdoc_documentation.rb, line 47
def exclude_classes=(strings)
  @exclude_classes = strings
end

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.

[Source]

# File bundles/as3/lib/sprout/tasks/asdoc_documentation.rb, line 54
def exclude_dependencies=(boolean)
  @exclude_dependencies = boolean
end

[Source]

# File bundles/as3/lib/sprout/tasks/asdoc_task.rb, line 262
    def exclude_expressions
      @exclude_expressions ||= []
    end

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

[Source]

# File bundles/as3/lib/sprout/tasks/asdoc_documentation.rb, line 59
def footer=(string)
  @footer = string
end

[Source]

# File bundles/as3/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 ="A list of classes to document. These classes must be in the source path. This is the default option.\n\nThis 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).\n"
      end
    
      add_param(:doc_namespaces, :strings) do |p|
        p.description ="A list of URIs whose classes should be documented. The classes must be in the source path.\n\nYou must include a URI and the location of the manifest file that defines the contents of this namespace.\n\nThis 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)\n"
      end

      add_param(:doc_sources, :paths) do |p|
        p.preprocessable = true
        p.description ="A list of files that should be documented. If a directory name is in the list, it is recursively searched.\n\nThis 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).\n"
      end
      
      add_param(:examples_path, :paths) do |p|
        p.description ="A collection of paths that asdoc will use to look for example files that were included using @includeExample.\n\nThis is an undocumented feature, but does seem to work.\n\nMore info:\nhttp://bugs.adobe.com/jira/browse/FLEXDOCS-476\n"
      end

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

      add_param(:exclude_dependencies, :boolean) do |p|
        p.description ="Whether all dependencies found by the compiler are documented. If true, the dependencies of the input classes are not documented.\n\nThe default value is false.\n"
      end

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

      add_param(:left_frameset_width, :number) do |p|
        p.description ="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.\n\nThe default value is 210 pixels.\n"
      end

      add_param(:library_path, :files) do |p|
        p.description ="Links SWC files to the resulting application SWF file. The compiler only links in those classes for the SWC file that are required.\n\nThe default value of the library-path option includes all SWC files in the libs directory and the current locale. These are required.\n\nTo point to individual classes or packages rather than entire SWC files, use the source-path option.\n\nIf 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.\n\nYou can use the += operator to append the new argument to the list of existing SWC files.\n\nIn 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.\n"
      end

      add_param(:load_config, :file) do |p|
        p.description ="Specifies the location of the configuration file that defines compiler options.\n\nIf you specify a configuration file, you can override individual options by setting them on the command line.\n\nAll relative paths in the configuration file are relative to the location of the configuration file itself.\n\nUse the += operator to chain this configuration file to other configuration files.\n\nFor 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).\n"
      end

      add_param(:main_title, :string) do |p|
        p.description ="The text that appears at the top of the HTML pages in the output documentation.\n\nThe default value is \"API Documentation\".\n"
      end

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

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

      add_param(:package, :string) do |p|
        p.description ="The descriptions to use when describing a package in the documentation. You can specify more than one package option.\n\nThe following example adds two package descriptions to the output:\nasdoc -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\"\n"
      end

      add_param(:source_path, :paths) do |p|
        p.preprocessable = true
        p.description ="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.\n\nYou can use wildcards to include all files and subdirectories of a directory.\n\nTo link an entire library SWC file and not individual classes or directories, use the library-path option.\n\nThe source path is also used as the search path for the component compiler's include-classes and include-resource-bundles options.\n\nYou can also use the += operator to append the new argument to the list of existing source path entries.\n"
      end

      add_param(:strict, :boolean) do |p|
        p.value = true
        p.show_on_false = true
        p.description ="Prints undefined property and function calls; also performs compile-time type checking on assignments and options supplied to method calls.\n\nThe default value is true.\n\nFor more information about viewing warnings and errors, see Viewing warnings and errors (http://livedocs.adobe.com/flex/2/docs/00001517.html#182413).\n"
      end

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

      add_param(:warnings, :boolean) do |p|
        p.description ="Enables all warnings. Set to false to disable all warnings. This option overrides the warn-warning_type options.\n\nThe default value is true.\n"
      end

      add_param(:window_title, :string) do |p|
        p.description ="The text that appears in the browser window in the output documentation.\n\nThe default value is \"API Documentation\".\n"
      end
    end

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.

[Source]

# File bundles/as3/lib/sprout/tasks/asdoc_documentation.rb, line 66
def left_frameset_width=(number)
  @left_frameset_width = number
end

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.

[Source]

# File bundles/as3/lib/sprout/tasks/asdoc_documentation.rb, line 81
def library_path=(files)
  @library_path = files
end

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).

[Source]

# File bundles/as3/lib/sprout/tasks/asdoc_documentation.rb, line 94
def load_config=(file)
  @load_config = file
end

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

The default value is "API Documentation".

[Source]

# File bundles/as3/lib/sprout/tasks/asdoc_documentation.rb, line 101
def main_title=(string)
  @main_title = string
end

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

[Source]

# File bundles/as3/lib/sprout/tasks/asdoc_documentation.rb, line 106
def namespace=(string)
  @namespace = string
end

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

[Source]

# File bundles/as3/lib/sprout/tasks/asdoc_documentation.rb, line 111
def output=(path)
  @output = path
end

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"

[Source]

# File bundles/as3/lib/sprout/tasks/asdoc_documentation.rb, line 119
def package=(string)
  @package = string
end

[Source]

# File bundles/as3/lib/sprout/tasks/asdoc_task.rb, line 274
    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

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.

[Source]

# File bundles/as3/lib/sprout/tasks/asdoc_documentation.rb, line 132
def source_path=(paths)
  @source_path = paths
end

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).

[Source]

# File bundles/as3/lib/sprout/tasks/asdoc_documentation.rb, line 141
def strict=(boolean)
  @strict = boolean
end

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.

[Source]

# File bundles/as3/lib/sprout/tasks/asdoc_documentation.rb, line 146
def templates_path=(paths)
  @templates_path = paths
end

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

The default value is true.

[Source]

# File bundles/as3/lib/sprout/tasks/asdoc_documentation.rb, line 153
def warnings=(boolean)
  @warnings = boolean
end

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

The default value is "API Documentation".

[Source]

# File bundles/as3/lib/sprout/tasks/asdoc_documentation.rb, line 160
def window_title=(string)
  @window_title = string
end

Protected Instance methods

Requires that @exclude_expressions is not nil.

[Source]

# File bundles/as3/lib/sprout/tasks/asdoc_task.rb, line 333
    def apply_exclusions_from_expression
      FileList[@exclude_expressions].each do |file_path|
        import_file = remove_source_path_from_file_path(file_path) || file_path
        import_class = filename_to_import_class(import_file)

        exclude_classes << import_class unless import_class.nil?
      end
    end

[Source]

# File bundles/as3/lib/sprout/tasks/asdoc_task.rb, line 300
    def execute(*args)
      update_helper_mode
      begin
        super
      rescue ExecutionError => e
        if(e.message.index('Warning:'))
          # MXMLC sends warnings to stderr....
          Log.puts(e.message.gsub('[ERROR]', '[WARNING]'))
        else
          raise e
        end
      end
    end

[Source]

# File bundles/as3/lib/sprout/tasks/asdoc_task.rb, line 351
    def filename_to_import_class(filename)
      name = filename.scan(/\w+/)
      # Ignore the AS file extension.
      name[0..-2].join('.') unless name[-1] != 'as'
    end

[Source]

# File bundles/as3/lib/sprout/tasks/asdoc_task.rb, line 342
    def remove_source_path_from_file_path(file)
        source_path.each do |source_dir|
          import_file = file.sub(Regexp.new("^#{source_dir}"),"")
          return import_file if import_file != file
        end
        
        return file
    end

[Source]

# File bundles/as3/lib/sprout/tasks/asdoc_task.rb, line 321
    def resolve_library(library_task)
      #TODO: Add support for libraries that don't get
      # copied into the project
      path = library_task.project_path
      if(path.match(/.swc$/))
        library_path << library_task.project_path
      else
        source_path << library_task.project_path
      end
    end

The AsDoc package includes an asDocHelper binary that is packaged up without the executable flag, calling Sprout::get_executable with this target will automatically chmod it to 744.

[Source]

# File bundles/as3/lib/sprout/tasks/asdoc_task.rb, line 317
    def update_helper_mode
      exe = Sprout.get_executable(gem_name, 'asdoc/templates/asDocHelper', gem_version)
    end

[Source]

# File bundles/as3/lib/sprout/tasks/asdoc_task.rb, line 292
    def validate_templates
      if(templates_path.size == 0)
        templates_dir = Sprout.get_executable(gem_name, 'asdoc/templates', gem_version)
        templates_dir = templates_dir.split('.exe').join('')
        templates_path << templates_dir
      end
    end

[Validate]