akka/akka-http
Create `@example` "include" pre-processor feature for java/scala-doc
Offen
#11 geöffnet am 26.08.2016
1 - triagedhelp wanted
Repository-Metriken
- Stars
- (1.311 Sterne)
- PR-Merge-Metriken
- (Durchschn. Merge 1T 10h) (2 gemergte PRs in 30 T)
Beschreibung
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