Wacky Fantasies in Documentation
Eric Kolotyluk <eric.kolotyluk <at> gmail.com>
2015-03-25 01:16:19 GMT
I was trying to get something working by reading the ScalaDoc. The
documentation was actually quite good by Scala standards, complete with
examples even. Unfortunately, there were some errors in the example code
that took me a while to figure out. Then I started to have this fantasy...
I wonder if it would be possible to define example code in scaladoc
comments such that when you generated your documentation at build time
in scaladoc, it would run the example code like a unit test, and fail
the build if the example code did not compile and execute.
One of my colleagues started buying into my fantasy and even suggested
that the scaladoc comments link to actual unit tests. Often studying
unit tests can be the best example of understanding a library or
framework. Indeed, I have seen a number of projects in GitHub that refer
you to the unit tests for examples of how to use the API or framework.
Of course this would imply that you would actually want to write good
scaladoc comments for your unit tests too. OMG - now I am speaking
heresy. What if the unit test framework actually help generate
meaningful documentation to explain what what going on?
My experience with documentation has been that it is often hard to test
documentation, to test that it is actually correct. What if we could
help improve documentation by using automated methods to test it, or at
least a part of it, such as examples.
You received this message because you are subscribed to the Google Groups "scala-debate" group.
To unsubscribe from this group and stop receiving emails from it, send an email to scala-debate+unsubscribe <at> googlegroups.com.
For more options, visit https://groups.google.com/d/optout.