lib/jsduck/options.rb in jsduck-5.2.0 vs lib/jsduck/options.rb in jsduck-5.3.0

@@ -16,10 +16,11 @@
 
     attr_accessor :output_dir
     attr_accessor :ignore_global
     attr_accessor :external_classes
     attr_accessor :ext4_events
+    attr_accessor :version
 
     # Customizing output
     attr_accessor :title
     attr_accessor :header
     attr_accessor :footer
@@ -46,10 +47,12 @@
     attr_accessor :search
     attr_accessor :ignore_html
 
     # Debugging
     attr_accessor :warnings_exit_nonzero
+    attr_accessor :cache
+    attr_accessor :cache_dir
     attr_accessor :template_dir
     attr_accessor :template_links
     attr_accessor :extjs_path
     attr_accessor :local_storage_db
     attr_accessor :touch_examples_ui
@@ -97,11 +100,11 @@
         # Special anything-goes type
         "Mixed",
       ]
       @ext4_events = nil
 
-      @version = "5.2.0"
+      @version = "5.3.0"
       # Customizing output
       @title = "Documentation - JSDuck"
       @header = "<strong>Documentation</strong> JSDuck"
       @footer = format_footer("Generated on {DATE} by {JSDUCK} {VERSION}.")
       @head_html = ""
@@ -130,10 +133,12 @@
       @search = {}
       @ignore_html = {}
 
       # Debugging
       @warnings_exit_nonzero = false
+      @cache = false
+      @cache_dir = nil
       @root_dir = File.dirname(File.dirname(File.dirname(__FILE__)))
       @template_dir = @root_dir + "/template-min"
       @template_links = false
       @extjs_path = "extjs/ext-all.js"
       @local_storage_db = "docs"
@@ -201,20 +206,26 @@
           "Directory to write all this documentation.",
           "",
           "This option is REQUIRED.  When the directory exists,",
           "it will be overwritten.  Give dash '-' as argument",
           "to write docs to STDOUT (works only with --export).") do |path|
-          @output_dir = path == "-" ? :stdout : canonical(path)
+          if path == "-"
+            @output_dir = :stdout
+          else
+            @output_dir = canonical(path)
+            @cache_dir = @output_dir + "/.cache" unless @cache_dir
+          end
         end
 
-        opts.on('--export=TYPE',
+        opts.on('--export=full/examples',
           "Exports docs in JSON.",
           "",
-          "TYPE is one of:",
+          "For each JavaScript class a JSON file gets written,",
+          "the contents of which are as follows:",
           "",
-          "- full     - full class docs.",
-          "- examples - extracts inline examples from classes.") do |format|
+          "- full     - docs and metadata for class and its members.",
+          "- examples - inline examples from classes and guides.") do |format|
           export_type = format.to_sym
           if [:full, :examples].include?(export_type)
             @export = export_type
           else
             Logger.fatal("Unsupported export type: '#{export_type}'")
@@ -661,10 +672,67 @@
             @ignore_html[tag] = true
           end
         end
 
         opts.separator ""
+        opts.separator "Performance:"
+        opts.separator ""
+
+        opts.on('-p', '--processes=COUNT',
+          "The number of parallel processes to use.",
+          "",
+          "Defaults to the number of processors/cores.",
+          "",
+          "Set to 0 to disable parallel processing completely.",
+          "This is often useful in debugging to get deterministic",
+          "results.",
+          "",
+          "In Windows this option is disabled.") do |count|
+          Util::Parallel.in_processes = count.to_i
+        end
+
+        opts.on('--[no-]cache',
+          "Turns parser cache on/off (EXPERIMENTAL).",
+          "",
+          "Defaults to off.",
+          "",
+          "When enabled, the results of parsing source files is saved",
+          "inside the JSDuck output directory. Next time JSDuck runs,",
+          "only the files that have changed are parsed again, others",
+          "are read from the cache.",
+          "",
+          "Note that switching between Ruby and/or JSDuck versions",
+          "invalidates the whole cache.  But changes in custom tags",
+          "don't invalidate the cache, so avoid caching when developing",
+          "your custom tags.",
+          "",
+          "To change the cache directory location, use --cache-dir.") do |enabled|
+          @cache = enabled
+        end
+
+        opts.on('--cache-dir=PATH',
+          "Directory where to cache the parsed source.",
+          "",
+          "Defaults to: <output-dir>/.cache",
+          "",
+          "Each project needs to have a separate cache directory.",
+          "Instead of writing the cache into the output directory,",
+          "one might consider keeping it together with the source",
+          "files.",
+          "",
+          "Note that JSDuck ensures that the <output-dir>/.cache",
+          "dir is preserved when the rest of the <output-dir> gets",
+          "wiped clean during the docs generation.  If you specify",
+          "cache dir like <output-dir>/.mycache, then this will also",
+          "be cleaned up during docs generation, and the caching",
+          "won't work.",
+          "",
+          "This option only has an effect when --cache is also used.",) do |path|
+          @cache_dir = path
+        end
+
+        opts.separator ""
         opts.separator "Debugging:"
         opts.separator ""
 
         opts.on('-v', '--verbose',
           "Turns on excessive logging.",
@@ -722,22 +790,9 @@
           "",
           "By default the colored output is on, but gets disabled",
           "automatically when output is not an interactive terminal",
           "(or when running on Windows system).") do |on|
           Logger.colors = on
-        end
-
-        opts.on('-p', '--processes=COUNT',
-          "The number of parallel processes to use.",
-          "",
-          "Defaults to the number of processors/cores.",
-          "",
-          "Set to 0 to disable parallel processing completely.",
-          "This is often useful in debugging to get deterministic",
-          "results.",
-          "",
-          "In Windows this option is disabled.") do |count|
-          Util::Parallel.in_processes = count.to_i
         end
 
         opts.on('--pretty-json',
           "Turns on pretty-printing of JSON.",
           "",