akka/akka-http
Create `@example` "include" pre-processor feature for java/scala-doc
Aperta
#11 aperta il 26 ago 2016
1 - triagedhelp wanted
Metriche repository
- Star
- (1311 stelle)
- Metriche merge PR
- (Merge medio 1g 10h) (2 PR mergiate in 30 g)
Descrizione
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