java - Scala 和 Java 中的注释约定 "//$example on:"和 "//$example off:"

Question

我在标准 Spark 发行版的“examples”文件夹中找到了它，评论如下:

// $example on:programmatic_schema$
import org.apache.spark.sql.Row
// $example off:programmatic_schema$
// $example on:init_session$
import org.apache.spark.sql.SparkSession
// $example off:init_session$
// $example on:programmatic_schema$
// $example on:data_types$
import org.apache.spark.sql.types._
// $example off:data_types$
// $example off:programmatic_schema$

object SparkSQLExample {

  // $example on:create_ds$
  case class Person(name: String, age: Long)
  // $example off:create_ds$

真的很难找到它的用途，我怀疑是某种自动文档工具？与 Java 和 Scala 相同。

Answer 1

Spark 使用自定义 Jekyll 插件来生成其文档，名为 include_example.rb 。这允许他们在 Markdown 源中使用 include_example 标签来包含存储库中的文件。

该插件包含以下描述:

# Select lines according to labels in code. Currently we use "$example on$" and "$example off$"
# as labels. Note that code blocks identified by the labels should not overlap.

因此，这些注释的存在是为了让他们可以更好地自动生成文档。

您在问题中显示的文件包含在 getting-started.md 中。通过 {% include_example create_df scala/org/apache/spark/examples/sql/SparkSQLExample.scala %}。 您可以在 Getting Started - Spark 3.0.0 Documentation 中看到它的完全渲染效果。 .

正如您所看到的，他们使用这些标签来去除每种语言的不相关信息/样板文件，并且只显示特定的位。不同的标签允许他们选择文件的不同部分。