Overview

Since API documentation is located in Scala source code files, the
process for contributing API documentation is similar to that of contributing bug-fixes
to the Scala code base, but without the requirement that there be an issue filed on JIRA
first. When forking/branching, just use a scaladoc/xxxx branch name, where xxxx is a
descriptive, but short branch name (e.g. scaladoc/future-object).
However, if an issue does exist, please use issue/NNNN, where NNNN is the ticket number,
instead.

Contribute API Documentation Bug Reports

One good way to contribute is by helping us to identify missing documentation. To do
this, browse the current API documentation
and identify missing, incorrect or inadequate documentation. A good place to start is
package objects for important packages (these often get overlooked for documentation
and are a good place for API overviews).

If you find an issue, please log it in the Scala issue trackerafter making sure it is not already logged as an issue. To help with
disambiguation, please use the following format for issue title:

Use an action describing the work required. E.g. Add, Document, Correct, Remove

Use the full package, class/trait/object name (or state package object if
that is the case).

Extremely short description of what to do.

More detail can (and should) go into the issue description, including a short
justification for the issue if it provides additional detail.

Here is an example of the title and description for an example API documentation issue:

Document scala.concurrent.Future object, include code examples

(note the explicit companion object called out in the title)

and the description:

The methods on the Future companion object are criticalfor using Futures effectively without blocking. Provide codeexamples of how methods like sequence, transform, fold andfirstCompletedOf should be used.

In addition to following these conventions, please add documentation and
community labels to the issue, and put them in the Documentation and API
component so that they show up in the correct issue filters.

Contribute New API Documentation

Required Reading

Please familiarize yourself with the following before contributing
new API documentation to save time, effort, mistakes and repetition.

Forking the Repo - follow the setup steps through
the Branch section. If providing new documentation related to an existing JIRA issue, use issue/NNNN
or ticket/NNNN as the guide states. If providing API documentation with no associated
JIRA issue, use scaladoc/xxxx instead.

Scaladoc’s interface
covers all of the features of Scaladoc’s interface, e.g. switching between
companions, browsing package object documentation, searching, token searches
and so on.

Prior to commit, be sure to read
A note about git commit messages and the Scala Project & Developer Guidelines.
Some of this latter document will clearly not apply (like the sections on providing tests,
however see below for some special requirements for documentation). Do still read
the whole document though, and pay close attention to the title and commit
message formats, noting present tense, length limits and that it must merge
cleanly. Remember that the title of the pull request will become the commit
message when merged. Also, be sure to assign one or more reviewers to the PR, list of
reviewers is at the bottom of this document, but the quick version is to add
Review by @heathermiller or Review by @dickwallin the pull request comments.

Extra Requirements for Scaladoc Documentation Commits

Although some of the requirements for bug fix pull requests are not needed for
API documentation commits, here are the step by step requirements to ensure your API documentation
PR is merged in smoothly:

Any and all code examples provided should be correct, compile and run as
expected (ensure this in the REPL or your IDE).

Spelling must be checked for all written language and code examples where
possible. Most editors have some spell checking feature available. Obviously
Scala code is likely to flag as mis-spelled sometimes, but any written language
should be checked. If you can also use a grammar checker, even better. We
will ask for spelling and grammar to be corrected before acceptance.

You must also run ant docs, fix any problems and check the formatting and
layout of your changes. Again, corrections will be required if formatting or
layout are inadequate. After running ant docs the generated documents can be
found under the build/scaladoc/ folders (probably in the library folder
but maybe under the others depending on what section of the Scala source you
are working on).

All of these steps are required to save time for both the reviewers and
contributors. It benefits everyone to ensure that the PR to merge process is
as smooth and streamlined as possible.