Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Commit fd14737

Browse files
retronymadriaanm
authored andcommitted
Address doc comment rot in the standard library.
- Match @param/@tparam names to the actual parameter name - Use @tparam for type parameters - Whitespace is required between `*` and `@` - Fix incorrect references to @define macros. - Use of monospace `` and {{{}}} (much more needed) - Remove `@param p1 ...` stubs, which appear in the generated docss. - But, retainsed `@param p1` stubs, assuming they will be filtered from the generated docs by SI-5795. - Avoid use of the shorthand `@param doc for the solitary param` (which works, but isn't recognized by the code inspection in IntelliJ I used to sweep through the problems) The remaining warnings from `ant docs` seem spurious, I suspect they are an unintended consequence of documenting extension methods. [scaladoc] /Users/jason/code/scala/src/library/scala/collection/TraversableOnce.scala:181: warning: Variable coll undefined in comment for method reduceOption in class Tuple2Zipped [scaladoc] def reduceOption[A1 >: A](op: (A1, A1) => A1): Option[A1] = reduceLeftOption(op) [scaladoc] ^
1 parent f388776 commit fd14737

File tree

6 files changed

+14
-18
lines changed

6 files changed

+14
-18
lines changed

‎src/library/scala/util/parsing/ast/Binders.scala‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -326,11 +326,11 @@ trait Binders extends AbstractSyntax with Mappable {
326326
// TODO: move this to some utility object higher in the scala hierarchy?
327327
/** Returns a given result, but executes the supplied closure before returning.
328328
* (The effect of this closure does not influence the returned value.)
329-
*
330-
* @param result the result to be returned
331-
* @param block code to be executed, purely for its side-effects
332329
*/
333330
trait ReturnAndDo[T]{
331+
/**
332+
* @param block code to be executed, purely for its side-effects
333+
*/
334334
def andDo(block: => Unit): T
335335
}
336336

‎src/library/scala/util/parsing/input/CharArrayReader.scala‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -21,10 +21,8 @@ object CharArrayReader {
2121
/** A character array reader reads a stream of characters (keeping track of their positions)
2222
* from an array.
2323
*
24-
* @param source an array of characters
24+
* @param chars an array of characters
2525
* @param index starting offset into the array; the first element returned will be `source(index)`
26-
* @param line the line number of the first element (counting from index `0` of `source`)
27-
* @param column the column number of the first element (counting from index `0` of `source`)
2826
*
2927
* @author Martin Odersky
3028
* @author Adriaan Moors

‎src/library/scala/util/parsing/input/OffsetPosition.scala‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -45,10 +45,9 @@ case class OffsetPosition(source: java.lang.CharSequence, offset: Int) extends P
4545
/** The column number referred to by the position; column numbers start at 1. */
4646
def column: Int = offset - index(line - 1) + 1
4747

48-
/** The contents of the line numbered `lnum` (must not contain a new-line character).
48+
/** The contents of the line numbered at the current offset.
4949
*
50-
* @param lnum a 1-based integer index into the `document`
51-
* @return the line at `lnum` (not including a newline)
50+
* @return the line at `offset` (not including a newline)
5251
*/
5352
def lineContents: String =
5453
source.subSequence(index(line - 1), index(line)).toString
@@ -59,7 +58,7 @@ case class OffsetPosition(source: java.lang.CharSequence, offset: Int) extends P
5958
/** Compare this position to another, by first comparing their line numbers,
6059
* and then -- if necessary -- using the columns to break a tie.
6160
*
62-
* @param `that` a `Position` to compare to this `Position`
61+
* @param that a `Position` to compare to this `Position`
6362
* @return true if this position's line number or (in case of equal line numbers)
6463
* column is smaller than the corresponding components of `that`
6564
*/

‎src/library/scala/util/parsing/input/PagedSeqReader.scala‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ object PagedSeqReader {
2323
/** A character array reader reads a stream of characters (keeping track of their positions)
2424
* from an array.
2525
*
26-
* @param source the source sequence
26+
* @param seq the source sequence
2727
* @param offset starting offset.
2828
*
2929
* @author Martin Odersky

‎src/library/scala/util/parsing/input/Position.scala‎

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -27,10 +27,7 @@ trait Position {
2727
/** The column number referred to by the position; column numbers start at 1. */
2828
def column: Int
2929

30-
/** The contents of the line numbered `lnum` (must not contain a new-line character).
31-
*
32-
* @param lnum a 1-based integer index into the `document`
33-
* @return the line at `lnum` (not including a newline)
30+
/** The contents of the line at this position. (must not contain a new-line character).
3431
*/
3532
protected def lineContents: String
3633

‎src/library/scala/util/parsing/input/StreamReader.scala‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -12,15 +12,17 @@ import java.io.BufferedReader
1212
import scala.collection.immutable.PagedSeq
1313

1414
/** An object to create a `StreamReader` from a `java.io.Reader`.
15-
*
16-
* @param in the `java.io.Reader` that provides the underlying
17-
* stream of characters for this Reader.
1815
*
1916
* @author Miles Sabin
2017
*/
2118
object StreamReader {
2219
final val EofCh = '032円'
2320

21+
/** Create a `StreamReader` from a `java.io.Reader`.
22+
*
23+
* @param in the `java.io.Reader` that provides the underlying
24+
* stream of characters for this Reader.
25+
*/
2426
def apply(in: java.io.Reader): StreamReader = {
2527
new StreamReader(PagedSeq.fromReader(in), 0, 1)
2628
}

0 commit comments

Comments
(0)

AltStyle によって変換されたページ (->オリジナル) /