Discussion: a way to maintain API reference guides

[lightbend]

Discussion: a way to maintain API reference guides

[eed3si9n]

The question is if this is out of scope for Paradox itself since it would require some tight integration with scaladoc and/or javadoc generators.

If it helps Akka HTTP docs, it's in scope.

[ktoso]

Yes, some support for these things would help us a lot. We have around 300 directives which all have docs pages, and they're very similar to their javadoc + include an example.

We wanted to automate it in some way:

• akka/akka-http#11
• akka/akka-http#10

because maintaining them is really hard.

[ktoso]

Basically what it is is "short description + long description + examples" + alphabetical list for them (java and scala DSL are separate classes, so we'd need to somehow say "list this one in the java docs"), it could be via @annotation in scaladocs