docSample

READ ME FIRST

This is the root package and the place to describe how to use your software tool, platform, or framework.

Code commenting caters to two distinct workflows. One is the user of the code and the other is the maintainer of the code. Scaladoc is used to create a software API that is entirely accessible through a web browser. So, it caters to the user of the code. This is a black box view of the code. Keep this in mind and write your scaladoc comments for an audience that knows very little about what your software does.

Because this is an API it is appropriate to:

• Plug the benefits of your software
• State which versions and build tools are known to work
• Provide links to a tutorial or demo to facilitate speedy evaluation
• Give step-by-step instructions to setup a build
• Provide plenty of descriptions and examples

Go to syntax to see how to insert markup.

How to Run Scaladoc
for this Example

(Scala will need to be downloaded and installed for this to work)

1. Make a directory for the generated web pages, md api
   
2. Change directory, cd api
   
3. Run the the tool,
   scaladoc <space separated list of directories with a *.scala wildcard>
   
   

Alternate Ways to Run Scaladoc

• Sbt can be used also by using the doc command. Be prepared though, Sbt may run an older version of Scaladoc.
  
  
• IntelliJ IDEA 11 comes with a "Generate Scaladoc" tool. (When I tried it Jan of 2012 it did not automatically support the project's CLASSPATH -- it may be working by the time you read this.)
  
  
• I understand there is an Eclipse plugin. I have not tried it.
  
  
• The tried-and-true method is to run Scaladoc with an Ant build. The Scala Language API is current built this way.
  

Note: Tested and built from the command prompt using:

• scaladoc v2.9.1
• scaladoc v2.10.0M1