Use of -d <output-dir> by scaladoc tool is effectively undocumented

[scabug]

The -d option allows an output directory to be selected for filing generated documentation under yet this is not effectively documented in the CLI help.

It's hidden in the scalac section and does not mentioned generated documents.

$ "C:\Program Files (x86)\scala\bin\scaladoc" -help
Usage: scaladoc <options> <source files>
where possible scaladoc options include:
  -author                                     Include authors.
  -diagrams                                   Create inheritance diagrams for classes, traits and packages.
  -diagrams-dot-path <path>                   The path to the dot executable used to generate the inheritance diagrams. Eg: /usr/bin/dot
  -diagrams-dot-restart <n>                   The number of times to restart a malfunctioning dot process before disabling diagrams (default: 5)
  -diagrams-dot-timeout <n>                   The timeout before the graphviz dot util is forcefully closed, in seconds (default: 10)
  -diagrams-max-classes <n>                   The maximum number of superclasses or subclasses to show in a diagram
  -diagrams-max-implicits <n>                 The maximum number of implicitly converted classes to show in a diagram
  -doc-footer <footer>                        A footer on every ScalaDoc page, by default the EPFL/Typesafe copyright notice. Can be overridden with a custom footer.
  -doc-format:<format>                        Selects in which format documentation is rendered (html) default:html
  -doc-generator <class-name>                 The fully qualified name of a doclet class, which will be used to generate the documentation
  -doc-no-compile <path>                      A directory containing sources which should be parsed, no more (e.g. AnyRef.scala)
  -doc-root-content <path>                    The file from which the root package documentation should be imported.
  -doc-source-url <url>                       A URL pattern used to link to the source file; the following variables are available: ▒{TPL_NAME}, ▒{TPL_OWNER} and respectively ▒{FILE_PATH}. For example, for `scala.collection.Seq`, the variables will be expanded to `Seq`, `scala.collection` and respectively `scala/collection/Seq` (without the backquotes). To obtain a relative path for ▒{FILE_PATH} instead of an absolute one, use the -sourcepath setting.
  -doc-title <title>                          The overall name of the Scaladoc site
  -doc-version <version>                      An optional version number, to be appended to the title
  -expand-all-types                           Expand all type aliases and abstract types into full template pages. (locally this can be done with the @template annotation)
  -groups                                     Group similar functions together (based on the @group annotation)
  -implicits                                  Document members inherited by implicit conversions.
  -implicits-hide:<implicit(s)>               Hide the members inherited by the given comma separated, fully qualified implicit conversions. Add dot (.) to include default conversions.
  -implicits-show-all                         Show members inherited by implicit conversions that are impossible in the default scope. (for example conversions that require Numeric[String] to be in scope)
  -no-link-warnings                           Avoid warnings for ambiguous and incorrect links.
  -no-prefixes                                Prevents generating prefixes in types, possibly creating ambiguous references, but significantly speeding up scaladoc.
  -raw-output                                 For each html file, create another .html.raw file containing only the text. (can be used for quickly diffing two scaladoc outputs)
  -skip-packages <<package1>:...:<packageN>>  A colon-delimited list of fully qualified package names that will be skipped from scaladoc.

Additional debug settings:
  -diagrams-debug                             Show debugging information for the diagram creation process.
  -implicits-debug                            Show debugging information for members inherited by implicit conversions.

Standard scalac options also available:
  -Dproperty=value                  Pass -Dproperty=value directly to the runtime system.
  -J<flag>                          Pass <flag> directly to the runtime system.
  -P:<plugin>:<opt>                 Pass an option to a plugin
  -X                                Print a synopsis of advanced options.
  -bootclasspath <path>             Override location of bootstrap class files.
  -classpath <path>                 Specify where to find user class files.
  -d <directory|jar>                destination for generated classfiles.
  -dependencyfile <file>            Set dependency tracking file.
  -deprecation                      Emit warning and location for usages of deprecated APIs.
  -doc-external-doc:<external-doc>  comma-separated list of classpath_entry_path#doc_URL pairs describing external dependencies.
  -encoding <encoding>              Specify character encoding used by source files.
  -explaintypes                     Explain type errors in more detail.
  -extdirs <path>                   Override location of installed extensions.
  -feature                          Emit warning and location for usages of features that should be imported explicitly.
  -g:<level>                        Set level of generated debugging info. (none,source,line,vars,notailcalls) default:vars
  -help                             Print a synopsis of standard options
  -implicits-sound-shadowing        Use a sound implicit shadowing calculation. Note: this interacts badly with usecases, so only use it if you haven't defined usecase for implicitly inherited members.
  -javabootclasspath <path>         Override java boot classpath.
  -javaextdirs <path>               Override java extdirs classpath.
  -language:<_,feature,-feature>    Enable or disable language features: `_' for all, `-language:help' to list
  -no-specialization                Ignore @specialize annotations.
  -nobootcp                         Do not use the boot classpath for the scala jars.
  -nowarn                           Generate no warnings.
  -optimise                         Generates faster bytecode by applying optimisations to the program
  -print                            Print program with Scala-specific features removed.
  -sourcepath <path>                Specify location(s) of source files.
  -target:<target>                  Target platform for object files. All JVM 1.5 targets are deprecated. (jvm-1.5,jvm-1.6,jvm-1.7,jvm-1.8) default:jvm-1.6
  -toolcp <path>                    Add to the runner classpath.
  -unchecked                        Enable additional warnings where generated code depends on assumptions.
  -uniqid                           Uniquely tag all identifiers in debugging output.
  -usejavacp                        Utilize the java.class.path in classpath resolution.
  -usemanifestcp                    Utilize the manifest in classpath resolution.
  -verbose                          Output messages about what the compiler is doing.
  -version                          Print product version and exit.
  @<file>                           A text file containing compiler arguments (options and source files)

[scabug]

Imported From: https://issues.scala-lang.org/browse/SI-9609?orig=1 Reporter: @janekdb Affected Versions: 2.11.7

[scabug]

@gourlaysama said: Maybe the description for -d can be amended to say that it just sets where the output goes (regardless of what kind of output), which is exactly what it does. It sort of makes sense for it to be in the scalac section since it is just a standard scalac option like the others.