From b13e5b5c327c5e3d799b3675e7799f47ab7ed7c5 Mon Sep 17 00:00:00 2001 From: Dave Copeland Date: Fri, 28 Oct 2011 08:21:04 -0400 Subject: [PATCH 1/2] corrected link to ScalaDoc instructions --- style/scaladoc.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/style/scaladoc.md b/style/scaladoc.md index b74e3852ef..a7abb5f2a1 100644 --- a/style/scaladoc.md +++ b/style/scaladoc.md @@ -39,8 +39,8 @@ of asterisks falls under the \_third\_ column, not the second, as is customary in Java. See the -[AuthorDocs](http://lampsvn.epfl.ch/trac/scala/wiki/Scaladoc/AuthorDocs) -at the EPFL Scala wiki for more technical info on formatting Scaladoc +[AuthorDocs](https://wiki.scala-lang.org/display/SW/Writing+Documentation) +on the Scala wiki for more technical info on formatting Scaladoc ## General Style From 9390524d02fd3ee39b9e7860a537c66b442f87bb Mon Sep 17 00:00:00 2001 From: Dave Copeland Date: Fri, 28 Oct 2011 08:30:30 -0400 Subject: [PATCH 2/2] fix various spelling errors --- style/declarations.md | 6 +++--- style/naming-conventions.md | 6 +++--- style/scaladoc.md | 30 +++++++++++++++--------------- 3 files changed, 21 insertions(+), 21 deletions(-) diff --git a/style/declarations.md b/style/declarations.md index 4258c78476..1340a33ef7 100644 --- a/style/declarations.md +++ b/style/declarations.md @@ -49,7 +49,7 @@ constructor arguments and extensions.: All class/object/trait members should be declared interleaved with newlines. The only exceptions to this rule are `var` and `val`. These may be declared without the intervening newline, but only if none of the -fields have scaladoc and if all of the fields have simple (max of 20-ish +fields have ScalaDoc and if all of the fields have simple (max of 20-ish chars, one line) definitions: class Foo { @@ -127,7 +127,7 @@ Generally speaking, you should choose whichever style is more readable on a case-by-case basis. For example, your method declaration may be very long, while the expression body may be quite short. In such a case, it may be more readable to put the expression on the next line rather -than making the declaration line unreadably long. +than making the declaration line too long. When the body of a method cannot be concisely expressed in a single line or is of a non-functional nature (some mutable state, local or @@ -180,7 +180,7 @@ There are three main reasons you should do this: When using implicit parameters, and you use the `implicit` keyword, it applies to the entire parameter list. Thus, if you want only some - parameters to be impicit, you must use multiple parameter lists. + parameters to be implicit, you must use multiple parameter lists. 3. For type inference diff --git a/style/naming-conventions.md b/style/naming-conventions.md index 7617cd3278..0f9d2afd80 100644 --- a/style/naming-conventions.md +++ b/style/naming-conventions.md @@ -166,10 +166,10 @@ any danger of mistakenly typing `name _` instead of `name_`. With heavy use of Scala's type inference, such a mistake could potentially lead to a very confusing error. -Note that the Java getter/setter paradigm was often used to work aroun a +Note that the Java getter/setter paradigm was often used to work around a lack of first class support for Properties and bindings. In Scala, there are libraries that support properties and bindings. The convention is to -use an immutable refrence to a property class that contains its own +use an immutable reference to a property class that contains its own getter and setter. For example: class Company { @@ -299,7 +299,7 @@ single letter, for clarity: class HigherOrderMap[Key[_], Value[_]] { ... } -The single letter form is (sometimes) acceptble for fundamental concepts +The single letter form is (sometimes) acceptable for fundamental concepts used throughout a codebase, such as `F[_]` for Functor and `M[_]` for Monad. diff --git a/style/scaladoc.md b/style/scaladoc.md index a7abb5f2a1..2174f478ee 100644 --- a/style/scaladoc.md +++ b/style/scaladoc.md @@ -1,25 +1,25 @@ --- layout: overview-large -title: Scaladoc +title: ScalaDoc partof: style-guide num: 10 --- It is important to provide documentation for all packages, classes, -traits, methods, and other members. Scaladoc generally follows the +traits, methods, and other members. ScalaDoc generally follows the conventions of Javadoc, however there are many additional features to make writing scaladoc simpler. In general, you want to worry more about substance and writing style -than in formatting. Scaladocs need to be useful to new users of the code +than in formatting. ScalaDocs need to be useful to new users of the code as well as experienced users. Achieving this is very simple: increase the level of detail and explanation as you write, starting from a terse summary (useful for experienced users as reference), while providing deeper examples in the detailed sections (which can be ignored by experienced users, but can be invaluable for newcomers). -The general format for a scaladoc comment should be as follows: +The general format for a ScalaDoc comment should be as follows: /** This is a brief description of what's being documented. * @@ -40,12 +40,12 @@ customary in Java. See the [AuthorDocs](https://wiki.scala-lang.org/display/SW/Writing+Documentation) -on the Scala wiki for more technical info on formatting Scaladoc +on the Scala wiki for more technical info on formatting ScalaDoc ## General Style -It is important to maintain a consistent style with scaladoc. It is also -important to target scaladoc to both those unfamiliar with your code and +It is important to maintain a consistent style with ScalaDoc. It is also +important to target ScalaDoc to both those unfamiliar with your code and experienced users who just need a quick reference. Here are some general guidelines: @@ -60,7 +60,7 @@ guidelines: - Create links to referenced Scala Library classes using the square-bracket syntax, e.g. `[[scala.Option]]` - Summarize a method's return value in the `@return` annotation, - leaving a longer description for the main scaladoc. + leaving a longer description for the main ScalaDoc. - If the documentation of a method is a one line description of what that method returns, do not repeat it with an `@return` annotation. - Document what the method *does do* not what the method *should do*. @@ -72,19 +72,19 @@ guidelines: - Use the wiki-style syntax instead of HTML wherever possible. - Examples should use either full code listings or the REPL, depending on what is needed (the simplest way to include REPL code is to - develop the examples in the REPL and paste it into the scaladoc). + develop the examples in the REPL and paste it into the ScalaDoc). - Make liberal use of `@macro` to refer to commonly-repeated values that require special formatting. ## Packages -Provide scaladoc for each package. This goes in a file named +Provide ScalaDoc for each package. This goes in a file named `package.scala` in your package's directory and looks like so (for the package `parent.package.name.mypackage`): package parent.package.name - /** This is the scaladoc for the package. */ + /** This is the ScalaDoc for the package. */ package object mypackage { } @@ -122,7 +122,7 @@ notation: ## Classes, Objects, and Traits Document all classes, objects, and traits. The first sentence of the -scaladoc should provide a summary of what the class or trait does. +ScalaDoc should provide a summary of what the class or trait does. Document all type parameters with `@tparam`. #### Classes @@ -131,7 +131,7 @@ If a class should be created using it's companion object, indicate as such after the description of the class (though leave the details of construction to the companion object). Unfortunately, there is currently no way to create a link to the companion object inline, however the -generated scaladoc will create a link for you in the class documentation +generated ScalaDoc will create a link for you in the class documentation output. If the class should be created using a constructor, document it using @@ -154,7 +154,7 @@ usage. Since objects can be used for a variety of purposes, it is important to document *how* to use the object (e.g. as a factory, for implicit methods). If this object is a factory for other objects, indicate as -such here, deferring the specifics to the scaladoc for the `apply` +such here, deferring the specifics to the ScalaDoc for the `apply` method(s). If your object *doesn't* use `apply` as a factory method, be sure to indicate the actual method names: @@ -177,7 +177,7 @@ sure to indicate the actual method names: } If your object holds implicit conversions, provide an example in the -scaladoc: +ScalaDoc: /** Implicits conversions and helpers for [[mypackage.Complex]] instances. *