akka/akka-http
View on GitHubCreate `@example` "include" pre-processor feature for java/scala-doc
Open
#11 opened on Aug 26, 2016
1 - triagedhelp wanted
Repository metrics
- Stars
- (1,311 stars)
- PR merge metrics
- (Avg merge 1d 10h) (2 merged PRs in 30d)
Description
We want to use this to power examples for all directives. It will make it easier to maintain the directive docs and would also address https://github.com/akka/akka/issues/18660
The idea is to keep examples somewhere where they are compiled as usual. Then we'd put a reference to an example directly into the scaladoc and then have a preprocessor (on sbt or scaladoc/javadoc level) that includes the snippet at that point into the scaladocs.
Example would be:
class ThingDirectives {
/**
* Does things.
*
* @example $root/akka-http-docs/blabla/ExampleDirectivesSpec.scala#example
*/
def example(t: String): Directive0 = ???
}
It should:
- Fail compilation if include does not exist
- Work for Scaladoc and Javadoc
- create a
<code>block basically - in Scaladoc there was an example feature I believe, check that
- allow us to move all directive method docs into scaladoc, so we don't have to maintain explicit docs pages for each of them