akka/akka-http
Create `@example` "include" pre-processor feature for java/scala-doc
Ouverte
#11 ouverte le 26 août 2016
1 - triagedhelp wanted
Métriques du dépôt
- Stars
- (1 311 étoiles)
- Métriques de merge PR
- (Merge moyen 1j 10h) (2 PRs mergées en 30 j)
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