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/.