[ https://issues.apache.org/jira/browse/SPARK-10383?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15138114#comment-15138114 ]
Xusen Yin commented on SPARK-10383: ----------------------------------- Update offline discussion with [~mengxr] here. Scaladoc provides a tag named *\@example* to add example code, like below: {code:scala} /** * @example * {{{ * val main = Main() * main.tell() * println() * }}} */ class Main { def tell(): Unit = println(1) } {code} Inside scala source code, we can see from [scala/src/compiler/scala/tools/nsc/doc/base/CommentFactoryBase.scala|https://github.com/scala/scala/blob/v2.10.4/src/compiler/scala/tools/nsc/doc/base/CommentFactoryBase.scala#L45] and [here|https://github.com/scala/scala/blob/v2.10.4/src/compiler/scala/tools/nsc/doc/base/CommentFactoryBase.scala#L277] to know how the Scaladoc extract example code and display it. So, if we have a comment preprocessor plugin, we can extract the text after *\@example*, then preprocess it. > Sync example code between API doc and user guide > ------------------------------------------------ > > Key: SPARK-10383 > URL: https://issues.apache.org/jira/browse/SPARK-10383 > Project: Spark > Issue Type: Brainstorming > Components: Documentation, ML, MLlib > Reporter: Xiangrui Meng > Assignee: Xiangrui Meng > > It would be nice to provide example code in both user guide and API docs. > However, it would become hard to keep the content in-sync. This JIRA is to > collect approaches/processes to make it feasible. > This is related to SPARK-10382, where we discuss how to move example code > from user guide markdown to `spark/examples/`. After that, we can look for > solutions that can pick up example code from `spark/examples` and make them > available in the API doc. Though I don't know any feasible solution right > now, those are some relevant projects: > * https://github.com/tkawachi/sbt-doctest > * http://www.doctester.org/ > It would be nice to hear more ideas. -- This message was sent by Atlassian JIRA (v6.3.4#6332) --------------------------------------------------------------------- To unsubscribe, e-mail: issues-unsubscr...@spark.apache.org For additional commands, e-mail: issues-h...@spark.apache.org