Please note that the Scala wikis are in a state of flux. We strongly encourage you to add content but avoid creating permanent links. URLs will frequently change. For our long-term plans see this post by the doc czar.
Skip to end of metadata
Go to start of metadata

Editing & regenerating Scaladoc

Step 1. Make your edits.

The source code for the Scala standard library is in src/library. Other components are in other subdirectories of src.

Scaladoc comments can be inherited, so if the doc you want to edit isn't in the source file you expected, try superclasses and traits. For example, the text at the top of http://www.scala-lang.org/api/current/scala/collection/parallel/immutable/ParHashMap.html actually comes not from src/library/scala/collection/parallel/immutable/ParHashMap.scala, but is inherited from /scala/src/library/scala/collection/parallel/ParIterableLike.scala.

Step 2 (optional). Regenerate the doc

If you're not confident your changes will appear correctly in the rendered HTML, you can run Scaladoc to render your changes.

SLOW METHOD (10+ minutes): At the top level of your local repo, run `ant docs.lib`. This builds the doc for the entire library. The results will appear under build/scaladoc. (There's also a docscomp which rebuilds the doc for the compiler, and a docs target which also builds man pages and other stuff. See build.xml for gory details.).
If ant fails with OutOfMemoryError, try

But that takes too long to get immediate feedback on whether your changes are working, so:

FAST METHOD A (<1 minute): For fast feedback, you can run Scaladoc on just the particular file you're editing. You could just say "scaladoc foo.scala" but then Scaladoc prints a ton of errors when you run it inside Scala's build directory. Please run Scaladoc outside of the directory. For example:

FAST METHOD B (<1 minute):

If you want to run with exactly the same way build.xml configures. One way to do this is to edit build.xml and change this line in the docs.lib task (line 1422):

changing */.scala to something concrete like Array.scala. Then only that file will be processed when you run `ant docs.lib`. A further speed tip: by default, docs.lib will recompile your changed file (even though you probably only changed the comments). To fool ant into skipping that step, after editing your sources do:

Probably there are other (more elegant?) solutions, but this works.

Submitting github Pull Requests

Step 1. Fork the Scala github repo.

While logged in to github, go to http://www.github.com/scala/scala, click "Fork" at the top right. 

At your command-line, type:

Configure remotes by… 

Step 2. Make your changes and commit.

It's recommended that you create a topic-branch to work on, for example, scala.Array-doc. 

To create that branch, enter 

And then to switch to that branch, 

Commit your changes to your forked repository:

(For the future: if you plan on continuing to contribute, don't forget to pull in changes to the scala repository by using git pull upstream.)

Step 3. Submit a pull request to the Scala github repo.

Assuming you've made one (or a few) commits that you'd like to submit as a pull-request to the official Scala github repository… 

While logged in to github, go to your forked repository (after you've committed changes) on github, make sure you're in the correct branch and click "Pull Request" at the top right. 

Preview the request (double check that the commits you've made are what you'd like to suggest as a pull-request), and write up a detailed description of your changes. Again, be sure to check the "Commits" and "diff" tabs to make sure everything is correct. Then click send. Easy.

For more a detailed description of submitting pull-requests, and for details on how to change the commits present in a pull-request, see http://help.github.com/send-pull-requests/

Step 4. Wait.

An army of skilled operators is standing by 24/7 at Typesafe headquarters to accept your pull requests. Once the request is accepted, your changes will appear in the docs for the next nightly, online at http://www.scala-lang.org/api/nightly/.

  • No labels