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

Contributing to Scaladoc 2 is useful, fun and (relatively) easy.

  • It is useful because there is a lot to do to improve Scaladoc, and because Gilles (that's me, the maintainer of Scaladoc), would rather spend his limited time improving Scala's structural types, or finishing the Scala reflection library.
  • It is fun because hacking Scaladoc offers almost immediate GUI reward. Furthermore, because it is easy, you can send in patches quickly.
  • It is (relatively) easy because Scaladoc is mostly a self-contained piece of code, so that hacking it doesn't require an advanced understanding of the compiler. On the other hand, as it still does access the compiler, it offers a way to approach some of its central data structures (most notable the symbol table) with little risk. Furthermore, Scaladoc is quite modular, so that you can change the wiki-syntax parser or the HTML generator without worrying much about the rest of the system. In fact, you can even contribute to Scaladoc if you don't know much Scala, as some of the interactive features are coded in JavaScript (arguably, this isn't in favour of the “fun” part).

What should you contribute

You can look at the proposed changes for ideas of patches to contribute, or look at the  tool bug list (note that some of the bugs in the list are related to the old Scaladoc and are not relevant to Scaladoc 2).

The proposed changes list is not an exhaustive catalogue of what can be improved in Scaladoc. As such, contributions for other features are also welcome. For the time being, I reserve the right to request changes to, or, in the worst case, reject contributions that go against the spirit of Scaladoc. Generally, it is preferable if you discuss your ideas on the bug or on the scala-internals mailing list.

Have a look at the top of this page for a list of what other work is happening on Scaladoc. You should probably pick something to contribute that isn't in this list. But if, for some reason, you want to contribute something that someone else is already working on, let me and the other person know.

Finally, once you have something working, submit a pull request to scala/scala on github. (please read the rules first)

Checklist for contributions

When you are ready to send your contribution, do the following:

  1. Check your contribution against the design guidelines to make sure that it fits (pay particular attention to the role of the model in the design).
  2. Check that your contribution is as small as possible, free of dead code, or of debugging output.
  3. Prepare a patch file (diff) against the head of the SVN trunk that can be applied at the root of the Scala repository (all files in the diff are relative to the Scala module root).
  4. Send me a mail with the patch and the necessary legal information, either:
  • A sentence stating that you own the source and are contributing it to the Scala project (for short contributions), or
  • A signed contributor license agreement (you have to send it once and it remains valid for further contributions).

Contributors

The following people (in alphabetical order) have kindly contributed code to Scaladoc 2:

Scaladoc 2 is based on older code written by the following people:

  • David Bernard
  • Vincent Cremet
  • Manohar Jonnalagedda
  • Stéphane Michleoud
  • Sean McDirmid
  • Geoffrey Washburn
  • No labels