Add scaladoc overview pages, update overview index, add forking and repo links

contribute.md

@@ -7,15 +7,15 @@ title: Contribute
 
 ## A Place to Build Documentation Together
 
-[docs.scala-lang.org](http://docs.scala-lang.org) was intended to make it easier for the Scala team and the community at large to easily collect, organize, and "make public" many different types of documentation while making it easy for users to find, interact, and help us improve that documentation. 
+[docs.scala-lang.org](http://docs.scala-lang.org) was intended to make it easier for the Scala team and the community at large to easily collect, organize, and "make public" many different types of documentation while making it easy for users to find, interact, and help us improve that documentation.
 
 This website is an open-source repository of official Scala documentation, hosted on [github](https://github.com/scala/scala.github.com), that is always ready for contributions.
 
 ### A Need for Better Documentation
 
-The availability, depth, and quality of documentation [is considered by many to be huge issue](http://www.google.com/moderator/#1/e=945de&t=945de.40). 
+The availability, depth, and quality of documentation [is considered by many to be huge issue](http://www.google.com/moderator/#1/e=945de&t=945de.40).
 
-As Scala continues to mature, it continues to attract more and more interested newcomers and potential adopters who are well accustomed to easy-to-find, abundant, quality documentation (found in other languages, like Java). For many, the learning curve becomes unnecessarily steep, and [people sometimes get frustrated](http://groups.google.com/group/scala-user/browse_thread/thread/29996782cb8428cd/5ade8462ba30b177). 
+As Scala continues to mature, it continues to attract more and more interested newcomers and potential adopters who are well accustomed to easy-to-find, abundant, quality documentation (found in other languages, like Java). For many, the learning curve becomes unnecessarily steep, and [people sometimes get frustrated](http://groups.google.com/group/scala-user/browse_thread/thread/29996782cb8428cd/5ade8462ba30b177).
 
 If we want Scala to be accessible to more programmers, clear, easy-to-find documentation is essential.
 
@@ -25,35 +25,38 @@ If you're interested in contributing to the Scala project in general, I argue th
 
 ### Content
 
-There are currently 3 different _types_ of documentation supported in this repository. 
+Currently, the _types_ of documentation supported in this repository are:
 
 - **Guides/Overviews**: Definitive guides/overviews of specific language features. Often long, detailed documents, often produced by members of the Scala team. An example is the excellent [Collections]({{ site.baseurl }}/overviews/collections/introduction.html) overview.
-- **Tutorials**: Bite-size, example-rich, and concise articles meant to get a developer up to speed quickly. 
+- **Tutorials**: Bite-size, example-rich, and concise articles meant to get a developer up to speed quickly.
 - **Cheatsheets**: Quick reference of Scala syntax and behaviors.
 
 ### Implementation
 
-This documentation repository is open-source, it lives in [github repository](https://github.com/scala/scala.github.com), and is always contribution-ready. 
+This documentation repository is open-source, it lives in [github repository](https://github.com/scala/scala.github.com), and is always contribution-ready.
 
 It's statically generated from [Markdown](http://en.wikipedia.org/wiki/Markdown) source using [Jekyll](https://github.com/mojombo/jekyll), and hosted on [GitHub Pages](http://pages.github.com/). This workflow was chosen so as to make it as easy as possible for core committers and the community alike to produce HTML documentation, and as easy as possible to publish it in a central location.
 
 The markdown syntax being used supports [Maruku](http://maruku.rubyforge.org/maruku.html) extensions, and has automatic syntax highlighting, without the need for any tags.
 
 ## Submitting Docs
 
-For one to contribute a document, one must simply fork the [repo](https://github.com/scala/scala.github.com), write their article in Markdown (example below), and submit a pull request. That's it. Likely after some edits and discussion, your document will be made live on [docs.scala-lang.org](http://docs.scala-lang.org).
+For one to contribute a document, one must simply
+[fork](https://help.github.com/articles/fork-a-repo/) the
+[repo](https://github.com/scala/scala.github.com), write their article in
+[Markdown](http://daringfireball.net/projects/markdown/syntax) (example below), and submit a pull request. That's it. Likely after some edits and discussion, your document will be made live on [docs.scala-lang.org](http://docs.scala-lang.org).
 
     ---
     layout: overview
     title: My Awesome Title
     ---
-    
+
     ## An h2 Header in Markdown
 
     And a paragraph, with a [link](http://www.scala-lang.org).
-	
+
 	One can contribute code by indenting it 4 spaces, or in-line by putting backticks around it like so, `def foo`
-	
+
 Everything else is automatically generated for you; tables of contents, and most index pages. And of course, the styling is already taken care of for you.
 
 ### Criteria for Docs to be Accepted
@@ -74,7 +77,7 @@ If you have something you're thinking about contributing, or that you're thinkin
 
 ### Guides/Overviews
 
-A guide or an overview that can be logically placed on **one** page must be placed in the directory `overviews/RELEVANT-CATEGORY/_posts` with the file name in the format `YYYY-MM-dd-title-separarted-by-dashes.md`, and header: 
+A guide or an overview that can be logically placed on **one** page must be placed in the directory `overviews/RELEVANT-CATEGORY/_posts` with the file name in the format `YYYY-MM-dd-title-separarted-by-dashes.md`, and header:
 
     ---
     layout: overview
@@ -85,12 +88,12 @@ The rest of the document should, of course, be written in [Markdown](http://en.w
 
 At the moment, `RELEVANT-CATEGORY` corresponds to only a single category, "core," because we are currently focusing on building up documentation of core libraries. However, expect more categories here in the future.
 
-If your document consists of **multiple** pages, like the [Collections]({{ site.baseurl }}/overviews/collections/index.html) overview, an ordering must be specified, by numbering documents in their logical order with `num`, and a name must be assigned to the collection of pages using `partof`. For example, the following header might be used for a document in the collections overview: 
+If your document consists of **multiple** pages, like the [Collections]({{ site.baseurl }}/overviews/collections/index.html) overview, an ordering must be specified, by numbering documents in their logical order with `num`, and a name must be assigned to the collection of pages using `partof`. For example, the following header might be used for a document in the collections overview:
 
     ---
     layout: overview-large
     title: YOUR TITLE
-    
+
     partof: collections
     num: 10
     ---
@@ -100,7 +103,7 @@ A **single** document in the collection must contain a tag in the header, `outof
     ---
     layout: overview-large
     title: YOUR TITLE
-    
+
     partof: collections
     num: 15
     outof: 15
@@ -143,7 +146,3 @@ For now, cheatsheets are assumed to be in the form of tables. To contribute a ch
     by: YOUR NAME
     about: SOME TEXT ABOUT THE CHEAT SHEET.
     ---
-
-
-
-

overviews/index.md

@@ -31,6 +31,14 @@ languages: [es, ja]
   * [Implicit Classes](/overviews/core/implicit-classes.html) <span class="label success">New in 2.10</span>
   * [Value Classes and Universal Traits](/overviews/core/value-classes.html) <span class="label success">New in 2.10</span>
 
+<div class="page-header-index">
+  <h2>Reference / Documentation</h2>
+</div>
+  * Scaladoc
+    * [Overview](/overviews/scaladoc/overview.html)
+    * [Basics](/overviews/scaladoc/basics.html)
+    * [Using Scaladoc Effectively](/overviews/scaladoc/usage.html)
+
 <div class="page-header-index">
   <h2>Parallel and Concurrent Programming</h2>
 </div>

overviews/scaladoc/basics.md

@@ -1,11 +1,10 @@
----
-layout: overview-large
-title: Basics, User-facing Scaladoc
-
-partof: scaladoc
-num: 2
-outof: 3
----
-
-This document is in progress and should be ready soon.
-
+<html>
+<head>
+<meta http-equiv="Refresh" content="0; url=http://docs.scala-lang.org/overviews/scaladoc/for-library-authors.html" />
+<title>Moved</title>
+</head>
+<body>
+<h1>Moved</h1>
+<p>This page has moved to <a href="http://docs.scala-lang.org/overviews/scaladoc/for-library-authors.html">http://docs.scala-lang.org/overviews/scaladoc/for-library-authors.html</a>.</p>
+</body>
+</html>

overviews/scaladoc/for-library-authors.md

@@ -0,0 +1,173 @@
+---
+layout: overview-large
+title: Scaladoc for Library Authors
+
+disqus: true
+
+partof: scaladoc
+num: 2
+outof: 3
+---
+
+Scaladoc is a documentation system that lives in the comments of Scala source code
+and is related to the code structure within which it is written. It is based on
+other comment based documentation systems like Javadoc, but with some extensions
+such as:
+
+- Markdown like formatting syntax may be used in the comments.
+- Extended @ tags (e.g. `@tparam`, `@see`, `@note`, `@example`, `@usecase`,
+  `@since`, etc.)
+- Macro definitions (defined values to be substituted in scaladoc).
+- Automatic inheritance of comments from a super-class/trait (may be used
+  effectively in combination with macro definitions).
+
+## Where to put Scaladoc
+
+Scaladoc comments go before the items they pertain to in a special comment block
+that starts with a `/**` and ends with a `*/`, like this:
+
+    /** Start the comment here
+      * and use the left star followed by a
+      * white space on every line.
+      *
+      * Even on empty paragraph-break lines.
+      *
+      * Note that the * on each line is aligned
+      * with the second * in /** so that the
+      * left margin is on the same column on the
+      * first line and on subsequent ones.
+      *
+      * The closing scaladoc tag goes on its own,
+      * separate line. E.g.
+      *
+      * Calculate the square of the given number
+      *
+      * @param d the Double to square
+      * @return the result of squaring d
+      */
+     def square(d: Double): Double = d * d
+
+In the example above, this Scaladoc comment is associated with the method
+`square` since it is right before it in the source code.
+
+Scaladoc comments can go before fields, methods, classes, traits, objects and
+even (especially) package objects. Scaladoc comments for package objects make
+a great place to put an overview of a specific package or API.
+
+For class *primary constructors* which in Scala coincide with the definition
+of the class itself, a `@constructor` tag is used to target a comment to be
+put on the primary constructor documentation rather than the class overview.
+
+## Tags
+Scaladoc uses `@` tags to provide specific detail fields in the comments. These
+include:
+
+
+### Class specific tags
+- `@constructor` placed in the class comment will describe the primary constructor.
+
+
+### Method specific tags
+- `@return` detail the return value from a method (one per method).
+
+
+### Constructor and/or Class tags
+- `@throws` what exceptions (if any) the method or constructor may throw.
+- `@param` detail a value parameter for a method or constructor, provide one
+  per parameter to the method/constructor.
+- `@tparam` detail a type parameter for a method, constructor or class. Provide
+  one per type parameter.
+
+
+### Usage tags
+- `@see` reference other sources of information like external document links or
+  related entities in the documentation.
+- `@note` add a note for pre or post conditions, or any other notable restrictions
+  or expectations.
+- `@example` for providing example code or related example documentation.
+- `@usecase` provide a simplified method definition for when the full method
+  definition is too complex or noisy. An example is (in the collections API),
+  providing documentation for methods that omit the implicit `canBuildFrom`.
+
+### Other tags
+- `@author` provide author information for the following entity
+- `@version` the version of the system or API that this entity is a part of.
+- `@since` like `@version` but defines the system or API that this entity was
+  *first* defined in.
+- `@todo` for documenting unimplemented features or unimplemented aspects of
+  an entity.
+- `@deprecated` marks the entity as deprecated, **providing both** the
+  replacement implementation that should be used and the version/date at which
+  this entity was deprecated.
+- `@migration` like deprecated but provides advanced warning of planned changes
+  ahead of deprecation. Same fields as `@deprecated`.
+- `@inheritdoc` take comments from a superclass as defaults if comments are not
+  provided locally.
+
+
+### Macros
+- `@define <name> <definition>` allows use of `$name` in other Scaladoc comments
+  within the same source file which will be expanded to the contents of
+  `<definition>`.
+
+
+## Comment Inheritance
+
+### Implicit
+If a comment is not provided for an entity at the current inheritance level, but
+is supplied for the overridden entity at a higher level in the inheritance
+hierarchy, the comment from the super-class will be used.
+
+Likewise if `@param`, `@tparam`, `@return` and other entity tags are ommitted
+but available from a superclass, those comments will be used.
+
+### Explicit
+For explicit comment inheritance, use the `@inheritdoc` tag.
+
+
+## Markdown style formatting
+
+It is still possible to embed HTML tags in Scaladoc (like with Javadoc), but
+not necessary most of the time as Markdown styles may be used instead.
+
+Some of the standard Markdown formatting available:
+
+    `monospace`
+    ``italic text``
+    ```bold text```
+    __underline__
+    ^superscript^
+    ,,subscript,,
+    [[entity link]], e.g. [[scala.collection.Seq]]
+    [[http://external.link External Link]],
+      e.g. [[http://scala-lang.org Scala Language Site]]
+
+### Other formatting notes
+
+- **Paragraphs** are started with one (or more) blank lines. `*` in the margin
+  for the comment is valid (and should be included) but the line should be
+  blank otherwise.
+- **Code blocks** are contained within `{{{` and `}}}` and may be multi-line.
+  Indentation is relative to the starting `*` for the comment.
+- **Headings** are defined with surrounding `=` characters, with more `=` denoting
+  subheadings. E.g. `=Heading=`, `==Sub-Heading==`, etc.
+- **List blocks** are a sequence of list items with the same style and level,
+  with no interruptions from other block styles. Unordered lists can be bulleted
+  using `-`, while numbered lists can be denoted using `1.`, `i.`, `I.`, `a.` for
+  the various numbering styles.
+
+## General Notes for Writing Scaladoc Comments ##
+
+- Concise is nice! Get to the point quickly, people have limited time to spend
+  on your documentation, use it wisely.
+- Omit unnecessary words. Prefer `returns X` rather than `this method returns X`,
+  and `does X,Y & Z` rather than `this method does X, Y and Z`.
+- DRY - don't repeat yourself. Resist duplicating the method description in the
+  `@return` tag and other forms of repetitive commenting.
+
+## More details on writing Scaladoc
+
+Further information on the formatting and style recommendations can be found in
+[Scala-lang scaladoc style guide](http://docs.scala-lang.org/style/scaladoc.html)
+and on the
+[Scala Wiki](https://wiki.scala-lang.org/display/SW/Writing+Documentation).

overviews/scaladoc/interface.md

@@ -0,0 +1,60 @@
+---
+layout: overview-large
+title: Using the Scaladoc Interface
+
+disqus: true
+
+partof: scaladoc
+num: 3
+outof: 3
+---
+
+Many Scala developers, including those with a great deal of experience, are
+unaware of some of the more powerful features of Scaladoc.
+
+The quickest way to find out about some of these is to check out this
+tutorial video:
+
+<iframe width="560" height="315" src="https://www.youtube.com/embed/GQxUEAXX_fE" frameborder="0" allowfullscreen></iframe>
+
+However, if you are in a hurry and just want a few pointers to things you
+may not have known about already, here are a few key points.
+
+## Scaladoc Features in Brief
+
+- The latest Scaladoc for the core Scala libraries can always be found at
+  [http://www.scala-lang.org/api/current](http://www.scala-lang.org/api/current).
+- The search box on the top left narrows the list of classes to those that
+  match a string search to your typing, use this to home in quickly on the class,
+  trait or object you are trying to find.
+- The letters underneath the search box list all fields, methods and other
+  tokens found during the creation of the Scaladoc. E.g. if you want to find
+  where the `.reverse` method you are using is defined, click on **R** in the
+  list of letters there, and then find in page to locate the `.reverse` method and
+  the list of implementing classes/traits.
+- The small icons on the left of the list of classes denote object `O`, class `C`
+  and/or trait `T`. Two icons show that this class or trait has a companion as
+  well. Clicking on the `O` takes you directly to the companion object instead
+  of the class or trait.
+- The same (but larger) icons at the top of the right pane in the title indicate
+  the same information (i.e. you are looking at the class, trait or object). If
+  the icon has a "peel over" corner on it, clicking will flip you between the
+  class/trait and its companion.
+- Methods and values may have information folded away that can be accessed by
+  clicking on the triangle to the left of the definition.
+- In the title bar, at the very top, is a breadcrumb list of the parent packages
+  and each package is a link to the package object documentation which sometimes
+  holds an overview of the package or API as a whole.
+- You can use the Hide and Focus links next to the packages to ignore a package
+  you no longer want to see in searches, or to concentrate only on that package
+  for searches.
+- By expanding linear supertypes triangle, you can see the linearized trait
+  definitions for the current class, trait or object.
+- Known subclasses lists all subclasses for this entity within the current
+  scaladoc.
+- Type hierarchy shows a graphical view of this class related to its super
+  classes and traits, immediate sub-types, and important related entities. The
+  graphics themselves are links to the various entities.
+- The link in the Source section takes you to the online source for the class
+  assuming it is available (and it certainly is for the core libraries and for
+  many other libraries).