Automatic ScalaDoc/ API doc generation

[Gavin Baumanis]

Hi there everyone.

Just thought I would ask how people go about creating ScalaDocs / API documentation for their projects?

I am aware of the syntax / style guides for annotating the source code...

But with all the auto-magic niceness that exists in Scala - I just thought I would check to see if there was a "not by hand" way of generating them?

I was thinking along the lines of a case class and how it generates the getters and setters automatically for us - why can't we get he API documentation auto-generated, too?

My reason for asking is that I had neglected creating the API docs as I created the source code - and was no going through all my source code to provide the appropriate annotations... and realised what a giant task (non in-line code documentation) - especially if you want the documentation to meaningful and accurate!

Thanks for any thoughts you might have!

[Naftoli Gugenheim]

What isn't already automatic that wouldn't require mind-reading?

--
You received this message because you are subscribed to the Google Groups "scala-user" group.
To unsubscribe from this group and stop receiving emails from it, send an email to scala-user+...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Stephen Compall]

On 2/5/17 4:33 AM, Gavin Baumanis wrote:

> But with all the auto-magic niceness that exists in Scala - I just
> thought I would check to see if there was a "not by hand" way of
> generating them?
>
> I was thinking along the lines of a case class and how it generates
> the getters and setters automatically for us - why can't we get he API
> documentation auto-generated, too?

Scaladoc does the best it can for this, by showing the names and types
of functions.

How good documentation this is depends on how specific the types you've
chosen are. String => String is not very explanatory, but [A](A,
List[A]): List[A] is quite a bit more specific.

One way to improve the Scaladoc of your API without adding Scaladoc
comments is to improve your types' specificity. This has the nice
side-effect of also constraining your implementations more, so fewer
tests are needed, not just fewer docs. By contrast, if you just use
String everywhere, you need more hand-written explanation of what each
String means, as well as tests to make sure you aren't mixing them up.

To the degree that we added information to your API that Scaladoc could
reliably emit as part of your docs, such information would also be part
of the type. So the type—which Scaladoc already emits for you—already
contains everything that Scaladoc could figure out, that is, assuming we
don't have the mind-reading system Naftoli mentions.

--
Stephen Compall

[Gavin Baumanis]

After reading the somewhat "bland" original email - I can certainly see why I would illicit "nafg" 's response...

But thanks Stephen for doing a little deciphering...

Your answer was very much in-line with what I was hoping to get help with....

"How can I alter my code, to create better documentation"?

Your answer though, has given me an even greater benefit...

"Use the type system as specifically as possible : for a better API".

the code it generates, then becomes a bonus... and the problem-solving cycles - turn to be more about code / software engineering, than documentation.

Which is a better use of expensive resources.

(Of course I am not saying that documentation should be ignored, either! 

It is evident I care about documentation - by asking how I can create "better" documentation....

But if I can get better documentation - by coding better.... that seems like a really good application of time and resources for all-round!

Thanks!