时间戳

首页 > 解决方案 > Scala 和 Java 中的注释约定 "// $example on:" 和 "// $example off:"

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

问题描述

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

// $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 也是如此。

标签： javascalaapache-spark

解决方案

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

该插件包含以下描述：

# 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中。通过您可以在Getting Started - Spark 3.0.0 文档{% include_example create_df scala/org/apache/spark/examples/sql/SparkSQLExample.scala %}.中看到这看起来是如何完全呈现的。

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

推荐阅读