Additional documentation of caching.

module JsDuck

  # Reads/writes parsed files in cache.

  #

  # When writing to cache:

  #

  # - makes MD5 hash of <file name> + <file contents>

  # - Dumps the the parsed data structure using Marshal into <md5>.dat

  #

  # When reading from cache:

  #

  # - makes MD5 hash of <file name> + <file contents>

  # - Reads the parsed data structure using Marshal from <md5>.dat

  #

  # Additionally a manifest.txt file is saved into the cache

  # directory, the contents of which is a string like the following:

  #

  #     Ruby: 1.9.3, JSDuck: 5.2.0

  #

  # This file is consulted before all other cache operations.  When

  # the version numbers in there don't match with current Ruby and

  # JSDuck versions, the whole cache gets invalidated - all cached

  # files get deleted.  This is to avoid problems with the Marshal

  # file format changes between Ruby versions and parsed data

  # structure changes between JSDuck versions.

  #

  # After all files have been checked into cache, the files that

  # weren't touched get deleted (using the #cleanup method).  This

  # ensures that the number of files in cache only grows when more

  # files are added to the documentation.

  #

  class Cache

    # Factory method to produce a cache object.  When caching is

        end

        opts.on('--[no-]cache',

          "Turn parser cache on/off (EXPERIMENTAL).",

          "Turns parser cache on/off (EXPERIMENTAL).",

          "",

          "Off by default.") do |enabled|

          "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") do |path|

          "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