Professional Scala

Chapter 8Documenting Your Code with Scaladoc

WHAT'S IN THIS CHAPTER?

• Understanding the structure of Scaladoc documentation
• Applying wiki syntax and tags
• Generating API documentation from commented source code
• Publishing your API documentation on the web
• Learning advanced documentation techniques

Code documentation can take many forms, ranging from manually authored web pages, README.md files, and generated API docs to no documentation at all. The nature of the code and the intended audience have a role to play in choosing what is right for your project. Suppose you have decided to document your code using Scaladoc. What's next? In this chapter you will learn about how to use Scaladoc syntax and the associated tooling to create documentation from Scaladoc comments embedded in your source code.

To get started you need to know what can be documented and what the formatting and linking options are. You also need to be aware of the tooling options you can apply to generate the API docs. Once you have your documentation generated, you need to know what to do next to expose it to a wider audience.

You will also learn about the structure of Scaladoc, both at the source level and in the rendered form. What options exist for generating the documentation from the command line, or from Maven or SBT? What are the limits of wiki syntax? Examples in this chapter will illustrate these general rules.

WHY DOCUMENT YOUR CODE?

“Lack of documentation is becoming a problem for acceptance. ...