Scaladoc

设置

语言
    此文档页面特定于 Scala 3，可能涵盖 Scala 2 中没有的新概念。除非另有说明，本页中的所有代码示例都假设你正在使用 Scala 3。

    本章列出了在调用 scaladoc 时可使用的配置选项。可以通过使用 -help 标志调用 scaladoc 来查找此处显示的某些信息。

    与 Scala 2 的 scaladoc 保持一致

    Scaladoc 已从头开始重写，而某些功能在新上下文中变得无用。如果您想知道与 scaladoc 旧标志的兼容性的当前状态，可以访问此问题以跟踪 进度。

    提供设置

    以命令行参数的形式提供 scaladoc 设置，例如，scaladoc -d output -project my-project target/scala-3.0.0-RC2/classes。如果从 sbt 调用，则分别更新 Compile / doc / scalacOptions 和 Compile / doc / target 的值，例如

    Compile / doc / target := file("output"),
Compile / doc / scalacOptions ++= Seq("-project", "my-project"),

    所有可用设置的概述

    -project

    项目的名称。提供与 Scala2 别名的兼容性，使用 -doc-title

    -project-version

    项目当前版本，显示在左上角。提供与 Scala2 别名的兼容性，使用 -doc-version

    项目徽标，显示在左上角。可以使用后缀 _dark 提供深色主题的单独徽标。如果徽标例如为 mylogo.png，则假定 mylogo_dark.png 为深色主题。提供与 Scala2 别名的兼容性，使用 -doc-logo

    -project-footer

    显示在页脚部分的字符串消息。提供与 Scala2 别名的兼容性，使用 -doc-footer

    -comment-syntax

    用于解析注释的样式语言。目前我们支持两种语法：markdown 或 wiki 如果未设置，scaladoc 默认 markdown

    -revision

    用于构建项目的修订版（分支或引用）。与 sourcelinks 一起使用很有用，以防止它们始终指向最新且可能发生更改的主版本。

    -source-links

    源链接提供文档和代码存储库中的文件之间的映射。

    示例源链接为：-source-links:docs=github://scala/scala3/main#docs

    接受的格式

    <sub-path>=<source-link>

    其中 <source-link> 是以下之一

    • github://<organization>/<repository>[/revision][#subpath] 将匹配 https://github.com/$organization/$repository/[blob|edit]/$revision[/$subpath]/$filePath[$lineNumber]，如果未提供修订版，则需要将修订版指定为 scaladoc 的参数
    • gitlab://<organization>/<repository> 将匹配 https://gitlab.com/$organization/$repository/-/[blob|edit]/$revision[/$subpath]/$filePath[$lineNumber]，如果未提供修订版，则需要将修订版指定为 scaladoc 的参数
    • <scaladoc-template>

    <scaladoc-template>是旧 scaladoc 中 doc-source-url 参数的格式。注意：我们仅支持 €{FILE_PATH_EXT}、€{TPL_NAME}、€{FILE_EXT}、€{FILE_PATH} 和 €{FILE_LINE} 模式。

    模板只能由 <sub-path> 表示的路径前缀定义的源子集定义。在这种情况下，模板中使用的路径将相对于 <sub-path> 进行相对化

    -external-mappings

    匹配类路径条目和外部文档的正则表达式之间的映射。

    外部映射示例：-external-mappings:.*scala.*::scaladoc3::https://scala-lang.org.cn/api/3.x/,.*java.*::javadoc::https://docs.oracle.com/javase/8/docs/api/

    映射的格式为 <regex>::[scaladoc3|scaladoc|javadoc]::<path>。您可以提供多个映射，用逗号分隔，如示例所示。

    -social-links

    指向社交网站的链接。例如

    -social-links:github::https://github.com/scala/scala3,discord::https://discord.com/invite/scala,twitter::https://twitter.com/scala_lang

    有效值格式为：[github|twitter|gitter|discord]::link。Scaladoc 还支持 custom::link::white_icon_name::black_icon_name。在这种情况下，图标必须存在于 images/ 目录中。

    -skip-by-id

    生成文档时要跳过的包或顶级类的标识符。

    -skip-by-regex

    生成文档时要跳过的包或顶级类的完全限定名称匹配的正则表达式。

    -doc-root-content

    应从中导入根包文档的文件。

    -author

    默认情况下，使用 @author Name Surname 在文档字符串中添加作者不会包含在生成的 html 文档中。如果您想明确地用作者标记类，请使用此标志运行 scaladoc。

    -groups

    将类似函数分组在一起（基于 @group 注释）

    -private

    显示所有类型和成员。除非指定，否则仅显示公共和受保护的类型和成员。

    -doc-canonical-base-url

    用作前缀的基本 URL，并向所有页面添加 canonical URL。搜索引擎可能会使用规范 URL 来选择您希望人们在搜索结果中看到的 URL。如果未设置，则不会生成规范 URL。

    -siteroot

    包含要从中生成文档的静态文件的目录。默认目录为 ./docs

    -no-link-warnings

    禁止成员查找中出现不明确或不正确的链接的警告。不影响资产等不正确链接的警告。

    -versions-dictionary-url

    指向包含词典的 JSON 文档的 URL：版本标签 -> 文档位置。JSON 文件具有单个属性 versions，该属性保存将特定文档版本的标签与指向其 index.html 的 URL 关联的词典。对于维护不同文档版本的库非常有用。

    示例 JSON 文件

    {
  "versions": {
    "3.0.x": "https://dotty.epfl.ch/3.0.x/docs/index.html",
    "Nightly": "https://dotty.epfl.ch/docs/index.html"
  }
}
    -snippet-compiler

    代码片段编译器参数提供了一种配置代码片段类型检查的方法。

    此设置接受格式为：args := arg{,args} arg := [path=]flag 的参数列表，其中 path 是代码片段所在源文件路径的前缀，flag 是代码片段将进行类型检查的模式。

    如果路径不存在，则该参数将用作所有不匹配路径的默认值。

    可用标志

    • compile - 启用代码片段检查。
    • nocompile - 禁用代码片段检查。
    • fail - 启用代码片段检查，断言代码片段无法编译。

    fail 标志非常适合于在编译期间最终会失败的代码片段，例如 Opaques 页面

    示例用法

    -snippet-compiler:my/path/nc=nocompile,my/path/f=fail,compile

    表示

    • 目录 my/path/nc 下的文件中的所有代码片段都不应编译
    • 目录 my/path/f 下的文件中的所有代码片段都应在编译期间失败
    • 所有其他代码片段都应成功编译
    -scastie-configuration

    为 Scastie 代码片段定义额外的 sbt 配置。例如，当您将外部库导入到代码片段中时，您需要添加相关的依赖项。

    "-scastie-configuration", """libraryDependencies += "org.apache.commons" % "commons-lang3" % "3.12.0""""
    -dynamic-side-menu

    使用 JavaScript 在浏览器中动态生成侧边菜单（左侧项目结构的树形概览），而不是将其嵌入到每个 HTML 文件中。这可以极大地减小输出的 HTML 文件大小。建议用于具有 1000 多个页面的项目。有关更多信息，请参阅 问题 18543。

    -Ysnippet-compiler-debug

    设置此选项会使代码片段编译器在编译（包装后）时打印代码片段。

    -Ydocument-synthetic-types

    将提供内在类型（例如 Any、Nothing）文档的页面包含在文档中。此设置仅对 stdlib 有用，因为 Scala 3 的 scaladoc 依赖于 TASTy 文件，但我们无法为内在类型提供这些文件，因为它们嵌入在编译器中。所有其他用户都不应关注此设置。

    ← 上一个

    此页面的贡献者

    内容
    此页面有问题？
         请帮助我们修复它！