Open jonas opened 8 years ago
eed3si9n
commented
8 years ago 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
commented
8 years ago 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:
because maintaining them is really hard.
ktoso
commented
8 years ago 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
Using "API reference guides" for lack of a better word describing documentation which is tightly coupled to the implementation but higher level than Scaladoc and Javadoc and more like UNIX man pages containing both API and example code snippets etc.
A good example is Akka HTTPs directive documentation and the related ticket akka/akka-http#25:
Scaladoc and Javadoc doesn't allow to easily organize and create such references. Furthermore, Scaladoc (up until 2.12) is not very search engine friendly, which is crucial for this type of documentation.
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. However this is also the case if cross references to source code is a goal as suggested in #25.