Соглашение о комментариях "// $ example on:" и "// $ example off:" в Scala и Java - PullRequest
Новая
       13

Соглашение о комментариях "// $ example on:" и "// $ example off:" в Scala и Java

0 голосов
/ 06 августа 2020

Я нашел его в папке «examples» стандартного дистрибутива 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.

1 Ответ

2 голосов
/ 06 августа 2020

Spark использует специальный плагин Jekyll для создания своей документации, который называется include_example.rb. Это позволяет им использовать тег include_example в своих источниках Markdown для включения файла из репозитория.

Плагин содержит следующее описание: 

# 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 %}. Вы можете увидеть, как это выглядит полностью отрисованным в Начало работы - Документация Spark 3.0.0 .

Как видите, они используют эти теги для удаления нерелевантной информации / шаблона каждого языка и отображать только c бит. Различные метки позволяют им выбирать разные биты файла.

...