Permalink
Browse files

Address some Scaladocrot

 - @param tags whose name drifted from the corresponding parameter
 - Remove or complete a few stray stub comments (@param foo ...)
 - Use @tparam where appropriate.
  • Loading branch information...
1 parent 6d94b35 commit d6527d5083d77f67d08749b800938c97e0fcf13a @retronym retronym committed Feb 25, 2013
@@ -65,7 +65,7 @@ class Pack200Task extends ScalaMatchingTask {
/** Set the flag to specify if file reordering should be performed. Reordering
* is used to remove empty packages and improve pack200 optimization.
- * @param keep
+ * @param x
* `'''true'''` to retain file ordering.
* `'''false'''` to optimize directory structure (DEFAULT). */
def setKeepFileOrder(x: Boolean) { keepFileOrder = x }
@@ -496,7 +496,7 @@ class Scalac extends ScalaMatchingTask with ScalacShared {
path.map(asString) mkString File.pathSeparator
/** Transforms a file into a Scalac-readable string.
- * @param path A file to convert.
+ * @param file A file to convert.
* @return A string-representation of the file like `/x/k/a.scala`. */
protected def asString(file: File): String =
file.getAbsolutePath()
@@ -563,7 +563,7 @@ class Scaladoc extends ScalaMatchingTask {
/** Transforms a file into a Scalac-readable string.
*
- * @param path A file to convert.
+ * @param file A file to convert.
* @return A string-representation of the file like `/x/k/a.scala`.
*/
private def asString(file: File): String =
@@ -805,8 +805,8 @@ class Global(var currentSettings: Settings, var reporter: Reporter)
/** Invalidates packages that contain classes defined in a classpath entry, and
* rescans that entry.
- * @param path A fully qualified name that refers to a directory or jar file that's
- * an entry on the classpath.
+ * @param paths Fully qualified names that refer to directories or jar files that are
+ * a entries on the classpath.
* First, causes the classpath entry referred to by `path` to be rescanned, so that
* any new files or deleted files or changes in subpackages are picked up.
* Second, invalidates any packages for which one of the following considitions is met:
@@ -303,7 +303,6 @@ trait DocComments { self: Global =>
/** Lookup definition of variable.
*
* @param vble The variable for which a definition is searched
- * @param owner The current owner in which variable definitions are searched.
* @param site The class for which doc comments are generated
*/
def lookupVariable(vble: String, site: Symbol): Option[String] = site match {
@@ -322,10 +321,10 @@ trait DocComments { self: Global =>
/** Expand variable occurrences in string `str`, until a fix point is reached or
* an expandLimit is exceeded.
*
- * @param str The string to be expanded
- * @param sym The symbol for which doc comments are generated
- * @param site The class for which doc comments are generated
- * @return Expanded string
+ * @param initialStr The string to be expanded
+ * @param sym The symbol for which doc comments are generated
+ * @param site The class for which doc comments are generated
+ * @return Expanded string
*/
protected def expandVariables(initialStr: String, sym: Symbol, site: Symbol): String = {
val expandLimit = 10
@@ -263,10 +263,6 @@ trait BasicBlocks {
/** Replaces `oldInstr` with `is`. It does not update
* the position field in the newly inserted instructions, so it behaves
* differently than the one-instruction versions of this function.
- *
- * @param iold ..
- * @param is ..
- * @return ..
*/
def replaceInstruction(oldInstr: Instruction, is: List[Instruction]): Boolean = {
assert(closed, "Instructions can be replaced only after the basic block is closed")
@@ -11,7 +11,7 @@ import scala.language.postfixOps
/** An extended version of compiler settings, with additional Scaladoc-specific options.
* @param error A function that prints a string to the appropriate error stream
- * @param print A function that prints the string, without any extra boilerplate of error */
+ * @param printMsg A function that prints the string, without any extra boilerplate of error */
class Settings(error: String => Unit, val printMsg: String => Unit = println(_)) extends scala.tools.nsc.Settings(error) {
/** A setting that defines in which format the documentation is output. ''Note:'' this setting is currently always
@@ -17,8 +17,6 @@ import scala.language.postfixOps
* Call `parse` to run the parser. Note that the parser is stateless and
* should only be built once for a given Scaladoc run.
*
- * @param reporter The reporter on which user messages (error, warnings) should be printed.
- *
* @author Manohar Jonnalagedda
* @author Gilles Dubochet */
trait CommentFactoryBase { this: MemberLookupBase =>
@@ -103,7 +103,7 @@ class HtmlFactory(val universe: doc.Universe, index: doc.Index) {
/** Generates the Scaladoc site for a model into the site root.
* A scaladoc site is a set of HTML and related files
* that document a model extracted from a compiler run.
- * @param model The model to generate in the form of a sequence of packages. */
+ */
def generate() {
def copyResource(subPath: String) {
@@ -45,7 +45,7 @@ abstract class Page {
/** Writes this page as a file. The file's location is relative to the
* generator's site root, and the encoding is also defined by the generator.
- * @param generator The generator that is writing this page. */
+ * @param site The generator that is writing this page. */
def writeFor(site: HtmlFactory): Unit
def kindToString(mbr: MemberEntity) =
@@ -84,7 +84,7 @@ abstract class Page {
}
/** A relative link from this page to some destination class entity.
- * @param destEntity The class or object entity that the link will point to. */
+ * @param destClass The class or object entity that the link will point to. */
def relativeLinkTo(destClass: TemplateEntity): String =
relativeLinkTo(templateToPath(destClass))
@@ -18,8 +18,6 @@ import scala.language.postfixOps
* Call `parse` to run the parser. Note that the parser is stateless and
* should only be built once for a given Scaladoc run.
*
- * @param reporter The reporter on which user messages (error, warnings) should be printed.
- *
* @author Manohar Jonnalagedda
* @author Gilles Dubochet */
trait CommentFactory extends base.CommentFactoryBase {
@@ -233,9 +233,6 @@ trait CompilerControl { self: Global =>
* prints its output and all defined values in a comment column.
*
* @param source The source file to be analyzed
- * @param keepLoaded If set to `true`, source file will be kept as a loaded unit afterwards.
- * If keepLoaded is `false` the operation is run at low priority, only after
- * everything is brought up to date in a regular type checker run.
* @param response The response.
*/
@deprecated("SI-6458: Instrumentation logic will be moved out of the compiler.","2.10.0")
@@ -278,7 +278,7 @@ class Lexer(rd: Reader) {
/** The current token is a delimiter consisting of given character, reads next token,
* otherwise raises an error.
- * @param c the given delimiter character to compare current token with
+ * @param ch the given delimiter character to compare current token with
* @throws MalformedInput if the current token `token` is not a delimiter, or
* consists of a character different from `c`.
*/
@@ -18,7 +18,7 @@ import scala.reflect.ClassTag
* Subclasses of `Pickler` each can write and read individual classes
* of values.
*
- * @param T the type of values handled by this pickler.
+ * @tparam T the type of values handled by this pickler.
*
* These Picklers build on the work of Andrew Kennedy. They are most closely inspired by
* Iulian Dragos' picklers for Scala to XML. See:
@@ -71,8 +71,8 @@ abstract class Pickler[T] {
def wrapped [U] (in: T => U)(out: U => T): Pickler[U] = wrappedPickler(this)(in)(out)
/** A conditional pickler obtained from the current pickler.
- * @param cond the condition to test to find out whether pickler can handle
- * some Scala value.
+ * @param p the condition to test to find out whether pickler can handle
+ * some Scala value.
*/
def cond(p: Any => Boolean): CondPickler[T] = conditionalPickler(this, p)
@@ -87,7 +87,7 @@ object Pickler {
/** A base class representing unpickler result. It has two subclasses:
* `UnpickleSucess` for successful unpicklings and `UnpickleFailure` for failures,
* where a value of the given type `T` could not be unpickled from input.
- * @param T the type of unpickled values in case of success.
+ * @tparam T the type of unpickled values in case of success.
*/
abstract class Unpickled[+T] {
/** Transforms success values to success values using given function,
@@ -125,7 +125,7 @@ object Pickler {
}
/** A class representing successful unpicklings
- * @param T the type of the unpickled value
+ * @tparam T the type of the unpickled value
* @param result the unpickled value
*/
case class UnpickleSuccess[+T](result: T) extends Unpickled[T]
@@ -361,8 +361,8 @@ abstract class CondPickler[T](val canPickle: Any => Boolean) extends Pickler[T]
* To unpickle a value, this unpickler is tried first. If it cannot read
* the input (as indicated by a `UnpickleFailure` result), then the
* alternative pickler is tried.
- * @param V The handled type of the returned pickler.
- * @param U The handled type of the alternative pickler.
+ * @tparam V The handled type of the returned pickler.
+ * @tparam U The handled type of the alternative pickler.
* @param that The alternative pickler.
*/
def | [V >: T, U <: V] (that: => CondPickler[U]): CondPickler[V] =
@@ -821,8 +821,8 @@ abstract class Mixin extends InfoTransform with ast.TreeDSL {
* Private fields used only in this initializer are subsequently set to null.
*
* @param clazz The class symbol
+ * @param lzyVal The symbol of this lazy field
* @param init The tree which initializes the field ( f = <rhs> )
- * @param fieldSym The symbol of this lazy field
* @param offset The offset of this field in the flags bitmap
*
* The result will be a tree of the form
@@ -618,7 +618,7 @@ trait Infer extends Checkable {
*
* @param tparams the type parameters of the method
* @param formals the value parameter types of the method
- * @param restp the result type of the method
+ * @param restpe the result type of the method
* @param argtpes the argument types of the application
* @param pt the expected return type of the application
* @return @see adjustTypeArgs
@@ -830,14 +830,11 @@ trait Infer extends Checkable {
* such that function type `ftpe` is applicable to
* `argtpes` and its result conform to `pt`?
*
- * @param undetparams ...
* @param ftpe the type of the function (often a MethodType)
- * @param argtpes the argument types; a NamedType(name, tp) for named
+ * @param argtpes0 the argument types; a NamedType(name, tp) for named
* arguments. For each NamedType, if `name` does not exist in `ftpe`, that
* type is set to `Unit`, i.e. the corresponding argument is treated as
* an assignment expression (@see checkNames).
- * @param pt ...
- * @return ...
*/
private def isApplicable(undetparams: List[Symbol], ftpe: Type,
argtpes0: List[Type], pt: Type): Boolean =
@@ -1192,7 +1189,7 @@ trait Infer extends Checkable {
* @param fn fn: the function that needs to be instantiated.
* @param undetparams the parameters that need to be determined
* @param args the actual arguments supplied in the call.
- * @param pt the expected type of the function application
+ * @param pt0 the expected type of the function application
* @return The type parameters that remain uninstantiated,
* and that thus have not been substituted.
*/
@@ -1243,7 +1240,7 @@ trait Infer extends Checkable {
*
* @param tree the constuctor that needs to be instantiated
* @param undetparams the undetermined type parameters
- * @param pt the expected result type of the instance
+ * @param pt0 the expected result type of the instance
*/
def inferConstructorInstance(tree: Tree, undetparams: List[Symbol], pt0: Type) {
val pt = abstractTypesToBounds(pt0)
@@ -1600,7 +1597,7 @@ trait Infer extends Checkable {
* with pt = WildcardType.
* Otherwise, if there is no best alternative, error.
*
- * @param argtpes contains the argument types. If an argument is named, as
+ * @param argtpes0 contains the argument types. If an argument is named, as
* "a = 3", the corresponding type is `NamedType("a", Int)'. If the name
* of some NamedType does not exist in an alternative's parameter names,
* the type is replaces by `Unit`, i.e. the argument is treated as an
@@ -574,7 +574,7 @@ trait TypeDiagnostics {
/** Report a type error.
*
- * @param pos0 The position where to report the error
+ * @param pos The position where to report the error
* @param ex The exception that caused the error
*/
def reportTypeError(context0: Context, pos: Position, ex: TypeError) {
@@ -2720,13 +2720,6 @@ trait Typers extends Adaptations with Tags {
}
}
-
- /**
- * @param fun ...
- * @param mode ...
- * @param pt ...
- * @return ...
- */
private def typedFunction(fun: Function, mode: Mode, pt: Type): Tree = {
val numVparams = fun.vparams.length
if (numVparams > definitions.MaxFunctionArity)
@@ -194,7 +194,7 @@ with scala.collection.mutable.FlatHashTable.HashUtils[T] {
*
* @param insertAt where to add the element (set to -1 to use its hashcode)
* @param comesBefore the position before which the element should be added to
- * @param elem the element to be added
+ * @param newEntry the element to be added
*
* If the element is to be inserted at the position corresponding to its hash code,
* the table will try to add the element in such a position if possible. Collisions are resolved
@@ -217,7 +217,7 @@ trait Names extends api.Names {
* this name from start, length if not found.
*
* @param c the character
- * @param start ...
+ * @param start the index from which to search
* @return the index of the first occurrence of c
*/
final def pos(c: Char, start: Int): Int = {
@@ -230,7 +230,7 @@ trait Names extends api.Names {
* in this name from start, length if not found.
*
* @param s the string
- * @param start ...
+ * @param start the index from which to search
* @return the index of the first occurrence of s
*/
final def pos(s: String, start: Int): Int = {
@@ -258,7 +258,7 @@ trait Names extends api.Names {
* name from start, -1 if not found.
*
* @param c the character
- * @param start ...
+ * @param start the index from which to search
* @return the index of the last occurrence of c
*/
final def lastPos(c: Char, start: Int): Int = {
@@ -28,8 +28,8 @@ abstract class UnPickler {
* from an array of bytes.
* @param bytes bytearray from which we unpickle
* @param offset offset from which unpickling starts
- * @param classroot the top-level class which is unpickled, or NoSymbol if inapplicable
- * @param moduleroot the top-level module which is unpickled, or NoSymbol if inapplicable
+ * @param classRoot the top-level class which is unpickled, or NoSymbol if inapplicable
+ * @param moduleRoot the top-level module which is unpickled, or NoSymbol if inapplicable
* @param filename filename associated with bytearray, only used for error messages
*/
def unpickle(bytes: Array[Byte], offset: Int, classRoot: Symbol, moduleRoot: Symbol, filename: String) {
@@ -1198,7 +1198,7 @@ private[reflect] trait JavaMirrors extends internal.SymbolTable with api.JavaUni
else sym.name.toString
/** The Java field corresponding to a given Scala field.
- * @param meth The Scala field.
+ * @param fld The Scala field.
*/
def fieldToJava(fld: TermSymbol): jField = fieldCache.toJava(fld) {
val jclazz = classToJava(fld.owner.asClass)

0 comments on commit d6527d5

Please sign in to comment.