$example和$example中的注释约定"// Scala on:“和"// Java 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

这允许他们在他们的Markdown源中使用include_example标签来包含来自repo的文件。

该插件包含以下描述：

根据代码中的标签选择行。目前我们使用"$example on$“和"$example off$”#作为标签。请注意，由标签标识的代码块不应重叠。

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

正如您所看到的，它们使用这些标记来剥离每种语言的无关信息/样板，并且只显示特定的部分。