From 838ec848b086f0e8f2bc2b075d693f5f77a5f6da Mon Sep 17 00:00:00 2001 From: corey-at-protenus <91161044+corey-at-protenus@users.noreply.github.com> Date: Fri, 30 Jun 2023 11:39:51 -0700 Subject: [PATCH 1/2] Update generate.md 3 changes: 1. note that installing via coursier may be needed. 2. correct link to "your first Scala program" 3. Include the current options for search engines and lazy developers Can split into multiple if requested. EG: 3 --- _overviews/scaladoc/generate.md | 156 +++++++++++++++++++++++++++++++- 1 file changed, 154 insertions(+), 2 deletions(-) diff --git a/_overviews/scaladoc/generate.md b/_overviews/scaladoc/generate.md index 0fbd38d533..bbbdf2e04f 100644 --- a/_overviews/scaladoc/generate.md +++ b/_overviews/scaladoc/generate.md @@ -32,7 +32,7 @@ For additional information about configuring Scaladoc in sbt, see the [Generate ## Using scaladoc command -If you use Scala commands directly to start a console with `scala` or compile with `scalac`, then you should have a `scaladoc` command-line utility, as well. This is a more advanced and less commonly used method of generating Scaladoc. +If you use Scala commands directly to start a console with `scala` or compile with `scalac`, then you should have a `scaladoc` command-line utility, as well. The `scaladoc` command can also be installed using Coursier: `coursier install scaladoc`. Using the command-line utility is a more advanced and less commonly used method of generating Scaladoc. $ scaladoc src/main/scala/App.scala model contains 1 documentable templates @@ -47,4 +47,156 @@ This command is harder to operate with more complex projects containing both mul The Scaladoc command exists because it preceded the development of sbt, but also because it is useful to the Scala development team with studying bug reports for Scaladoc. -More information on directly using the Scala commands, like `scaladoc`, is discussed at [your first lines of Scala](https://www.scala-lang.org/documentation/your-first-lines-of-scala.html). +More information on directly using the Scala commands, like `scaladoc`, is discussed at [your first Scala program](https://docs.scala-lang.org/scala3/book/taste-hello-world.html). + +## Options Reference + +The scaladoc options as of version 3.3.0 are: + +``` +% scaladoc --help +Usage: scaladoc +where possible standard options include: + -Dproperty=value Pass -Dproperty=value directly to the runtime system. + -J Pass directly to the runtime system. + -P Pass an option to a plugin, e.g. -P:: + -V Print a synopsis of verbose options. + -W Print a synopsis of warning options. + -Wconf Configure compiler warnings. + -Werror Fail the compilation if there are any warnings. + -X Print a synopsis of advanced options. + -Y Print a synopsis of private options. + -author Include authors. + -bootclasspath Override location of bootstrap class files. + -classpath Specify where to find user class files. + Default . + -color Colored output + Default always + Choices : always, never + -comment-syntax + -coverage-out Destination for coverage classfiles and + instrumentation data. + -d Destination for generated classfiles. + -default-template The static site is generating empty files for indexes + that haven't been provided explicitly in a + sidebar/missing index.html in directory. User can + specify what default template should be used for such + indexes. It can be useful for providing generic + templates that interpolate some common settings, like + title, or can have some custom html embedded. + -deprecation Emit warning and location for usages of deprecated + APIs. + -doc-canonical-base-url A base URL to use as prefix and add `canonical` URLs + to all pages. The canonical URL may be used by search + engines to choose the URL that you want people to see + in search results. If unset no canonical URLs are + generated. + -doc-external-doc Legacy option from Scala 2. Mapping betweeen path and + external documentation. Use -external-mappings + instead. + -doc-root-content The file from which the root package documentation + should be imported. + -doc-source-url Legacy option from Scala 2. Use -source-links instead. + -encoding Specify character encoding used by source files. + Default UTF-8 + -explain Explain errors in more detail. + -explain-types Explain type errors in more detail (deprecated, use + -explain instead). + -extdirs Override location of installed extensions. + -external-mappings Mapping between regexes matching classpath entries and + external documentation. + 'regex::[scaladoc|scaladoc|javadoc]::path' syntax is + used + -feature Emit warning and location for usages of features that + should be imported explicitly. + -from-tasty Compile classes from tasty files. The arguments are + .tasty or .jar files. + -groups Group similar functions together (based on the @group + annotation) + -help Print a synopsis of standard options. + -indent Together with -rewrite, remove {...} syntax when + possible due to significant indentation. + -java-output-version Compile code with classes specific to the given + version of the Java platform available on the + classpath and emit bytecode for this version. + Corresponds to -release flag in javac. + Choices : 8, 9, 10, 11 + -javabootclasspath Override java boot classpath. + -javaextdirs Override java extdirs classpath. + -language Enable one or more language features. + -new-syntax Require `then` and `do` in control expressions. + -no-indent Require classical {...} syntax, indentation is not + significant. + -no-link-warnings Avoid warnings for ambiguous and incorrect links in + members look up. Doesn't affect warnings for incorrect + links of assets etc. + -nowarn Silence all warnings. + -old-syntax Require `(...)` around conditions. + -pagewidth Set page width + Default 80 + -print-lines Show source code line numbers. + -print-tasty Prints the raw tasty. + -private Show all types and members. Unless specified, show + only public and protected types and members. + -project The name of the project. + -project-footer A footer on every Scaladoc page. + -project-logo Path to the file that contains the project's logo. + Provided path can be absolute or relative to the + project root directory. + -project-url The source repository of your project. + -project-version The current version of your project. + -quick-links List of quick links that is displayed in the header of + documentation. + -revision Revision (branch or ref) used to build project project + -rewrite When used in conjunction with a `...-migration` source + version, rewrites sources to migrate to new version. + -scalajs Compile in Scala.js mode (requires scalajs-library.jar + on the classpath). +-scalajs-genStaticForwardersForNonTopLevelObjects + Generate static forwarders even for non-top-level + objects (Scala.js only) + -scalajs-mapSourceURI rebases source URIs from uri1 to uri2 (or to a + relative URI) for source maps (Scala.js only) + -scastie-configuration Additional configuration passed to Scastie in code + snippets + -semanticdb-target Specify an alternative output directory for SemanticDB + files. + -siteroot A directory containing static files from which to + generate documentation. + Default ./docs + -skip-by-id Identifiers of packages or top-level classes to skip + when generating documentation + -skip-by-regex Regexes that match fully qualified names of packages + or top-level classes to skip when generating + documentation + -skip-packages Deprecated, please use `-skip-by-id` or + `-skip-by-regex` + -snippet-compiler + -social-links Links to social sites. + '[github|twitter|gitter|discord]::link' syntax is + used. + -source source version + Default 3.3 + Choices : 3.0-migration, 3.0, 3.1, 3.2-migration, 3.2, + 3.3-migration, 3.3, future-migration, future + -source-links Source links provide a mapping between file in + documentation and code repository. + -sourcepath Specify location(s) of source files. + -sourceroot Specify workspace root directory. + Default . + -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. + -verbose Output messages about what the compiler is doing. + -version Print product version and exit. +-versions-dictionary-url A URL pointing to a JSON document containing a + dictionary `version label -> documentation location`. + The JSON file has single property "versions" that + holds dictionary of labels of specific docs and URL + pointing to their index.html top-level file. Useful + for libraries that maintain different versions of + their documentation. + @ A text file containing compiler arguments (options and + source files). +``` From a88e34cd72a005ac1ba8f1a7c8999f7a75d84a19 Mon Sep 17 00:00:00 2001 From: corey-at-protenus <91161044+corey-at-protenus@users.noreply.github.com> Date: Tue, 8 Aug 2023 10:03:06 -0700 Subject: [PATCH 2/2] Remove options block per feedback --- _overviews/scaladoc/generate.md | 151 -------------------------------- 1 file changed, 151 deletions(-) diff --git a/_overviews/scaladoc/generate.md b/_overviews/scaladoc/generate.md index bbbdf2e04f..c0ba234af5 100644 --- a/_overviews/scaladoc/generate.md +++ b/_overviews/scaladoc/generate.md @@ -49,154 +49,3 @@ The Scaladoc command exists because it preceded the development of sbt, but also More information on directly using the Scala commands, like `scaladoc`, is discussed at [your first Scala program](https://docs.scala-lang.org/scala3/book/taste-hello-world.html). -## Options Reference - -The scaladoc options as of version 3.3.0 are: - -``` -% scaladoc --help -Usage: scaladoc -where possible standard options include: - -Dproperty=value Pass -Dproperty=value directly to the runtime system. - -J Pass directly to the runtime system. - -P Pass an option to a plugin, e.g. -P:: - -V Print a synopsis of verbose options. - -W Print a synopsis of warning options. - -Wconf Configure compiler warnings. - -Werror Fail the compilation if there are any warnings. - -X Print a synopsis of advanced options. - -Y Print a synopsis of private options. - -author Include authors. - -bootclasspath Override location of bootstrap class files. - -classpath Specify where to find user class files. - Default . - -color Colored output - Default always - Choices : always, never - -comment-syntax - -coverage-out Destination for coverage classfiles and - instrumentation data. - -d Destination for generated classfiles. - -default-template The static site is generating empty files for indexes - that haven't been provided explicitly in a - sidebar/missing index.html in directory. User can - specify what default template should be used for such - indexes. It can be useful for providing generic - templates that interpolate some common settings, like - title, or can have some custom html embedded. - -deprecation Emit warning and location for usages of deprecated - APIs. - -doc-canonical-base-url A base URL to use as prefix and add `canonical` URLs - to all pages. The canonical URL may be used by search - engines to choose the URL that you want people to see - in search results. If unset no canonical URLs are - generated. - -doc-external-doc Legacy option from Scala 2. Mapping betweeen path and - external documentation. Use -external-mappings - instead. - -doc-root-content The file from which the root package documentation - should be imported. - -doc-source-url Legacy option from Scala 2. Use -source-links instead. - -encoding Specify character encoding used by source files. - Default UTF-8 - -explain Explain errors in more detail. - -explain-types Explain type errors in more detail (deprecated, use - -explain instead). - -extdirs Override location of installed extensions. - -external-mappings Mapping between regexes matching classpath entries and - external documentation. - 'regex::[scaladoc|scaladoc|javadoc]::path' syntax is - used - -feature Emit warning and location for usages of features that - should be imported explicitly. - -from-tasty Compile classes from tasty files. The arguments are - .tasty or .jar files. - -groups Group similar functions together (based on the @group - annotation) - -help Print a synopsis of standard options. - -indent Together with -rewrite, remove {...} syntax when - possible due to significant indentation. - -java-output-version Compile code with classes specific to the given - version of the Java platform available on the - classpath and emit bytecode for this version. - Corresponds to -release flag in javac. - Choices : 8, 9, 10, 11 - -javabootclasspath Override java boot classpath. - -javaextdirs Override java extdirs classpath. - -language Enable one or more language features. - -new-syntax Require `then` and `do` in control expressions. - -no-indent Require classical {...} syntax, indentation is not - significant. - -no-link-warnings Avoid warnings for ambiguous and incorrect links in - members look up. Doesn't affect warnings for incorrect - links of assets etc. - -nowarn Silence all warnings. - -old-syntax Require `(...)` around conditions. - -pagewidth Set page width - Default 80 - -print-lines Show source code line numbers. - -print-tasty Prints the raw tasty. - -private Show all types and members. Unless specified, show - only public and protected types and members. - -project The name of the project. - -project-footer A footer on every Scaladoc page. - -project-logo Path to the file that contains the project's logo. - Provided path can be absolute or relative to the - project root directory. - -project-url The source repository of your project. - -project-version The current version of your project. - -quick-links List of quick links that is displayed in the header of - documentation. - -revision Revision (branch or ref) used to build project project - -rewrite When used in conjunction with a `...-migration` source - version, rewrites sources to migrate to new version. - -scalajs Compile in Scala.js mode (requires scalajs-library.jar - on the classpath). --scalajs-genStaticForwardersForNonTopLevelObjects - Generate static forwarders even for non-top-level - objects (Scala.js only) - -scalajs-mapSourceURI rebases source URIs from uri1 to uri2 (or to a - relative URI) for source maps (Scala.js only) - -scastie-configuration Additional configuration passed to Scastie in code - snippets - -semanticdb-target Specify an alternative output directory for SemanticDB - files. - -siteroot A directory containing static files from which to - generate documentation. - Default ./docs - -skip-by-id Identifiers of packages or top-level classes to skip - when generating documentation - -skip-by-regex Regexes that match fully qualified names of packages - or top-level classes to skip when generating - documentation - -skip-packages Deprecated, please use `-skip-by-id` or - `-skip-by-regex` - -snippet-compiler - -social-links Links to social sites. - '[github|twitter|gitter|discord]::link' syntax is - used. - -source source version - Default 3.3 - Choices : 3.0-migration, 3.0, 3.1, 3.2-migration, 3.2, - 3.3-migration, 3.3, future-migration, future - -source-links Source links provide a mapping between file in - documentation and code repository. - -sourcepath Specify location(s) of source files. - -sourceroot Specify workspace root directory. - Default . - -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. - -verbose Output messages about what the compiler is doing. - -version Print product version and exit. --versions-dictionary-url A URL pointing to a JSON document containing a - dictionary `version label -> documentation location`. - The JSON file has single property "versions" that - holds dictionary of labels of specific docs and URL - pointing to their index.html top-level file. Useful - for libraries that maintain different versions of - their documentation. - @ A text file containing compiler arguments (options and - source files). -```