[
https://issues.apache.org/jira/browse/SPARK-10383?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15138114#comment-15138114
]
Xusen Yin edited comment on SPARK-10383 at 2/9/16 12:30 AM:
------------------------------------------------------------
Update offline discussion with [~mengxr] here.
Scaladoc provides a tag named *\@example* to add example code, like below:
{code:title=example.scala|theme=FadeToGrey|linenumbers=true|language=scala|firstline=0001|collapse=false}
/**
* @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.
was (Author: yinxusen):
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: [email protected]
For additional commands, e-mail: [email protected]
