diff options
author | michelou <michelou@epfl.ch> | 2008-02-25 17:34:15 +0000 |
---|---|---|
committer | michelou <michelou@epfl.ch> | 2008-02-25 17:34:15 +0000 |
commit | 2d39db44e2f74571fa4dd407f5f56fb568b37360 (patch) | |
tree | 064526cd3e26f74d19cab924e8788bbdde751b4b /src | |
parent | befbc9d2c1ec99b07ea1aa4bc853440d4cb9a689 (diff) | |
download | scala-2d39db44e2f74571fa4dd407f5f56fb568b37360.tar.gz scala-2d39db44e2f74571fa4dd407f5f56fb568b37360.tar.bz2 scala-2d39db44e2f74571fa4dd407f5f56fb568b37360.zip |
fixed scaladoc comments
Diffstat (limited to 'src')
-rw-r--r-- | src/compiler/scala/tools/nsc/doc/DefaultDocDriver.scala | 20 | ||||
-rw-r--r-- | src/compiler/scala/tools/nsc/doc/ModelAdditions.scala | 320 | ||||
-rw-r--r-- | src/library/scala/StringBuilder.scala | 146 |
3 files changed, 301 insertions, 185 deletions
diff --git a/src/compiler/scala/tools/nsc/doc/DefaultDocDriver.scala b/src/compiler/scala/tools/nsc/doc/DefaultDocDriver.scala index 2d836e1297..56f6c09d9f 100644 --- a/src/compiler/scala/tools/nsc/doc/DefaultDocDriver.scala +++ b/src/compiler/scala/tools/nsc/doc/DefaultDocDriver.scala @@ -32,7 +32,7 @@ abstract class DefaultDocDriver extends DocDriver with ModelFrames with ModelToX } def process(settings: Settings, units: Iterator[CompilationUnit]) { - process(units) + process(units) } def process(units: Iterator[CompilationUnit]) { @@ -74,8 +74,8 @@ abstract class DefaultDocDriver extends DocDriver with ModelFrames with ModelToX additions0.init copyResources val packages0 = sort(allClasses.keySet) - new AllPackagesFrame with Frame { def packages = packages0; } - new PackagesContentFrame with Frame { def packages = packages0; } + new AllPackagesFrame with Frame { def packages = packages0 } + new PackagesContentFrame with Frame { def packages = packages0 } new NavigationFrame with Frame { } new ListClassFrame with Frame { def classes = for (p <- allClasses; d <- p._2) yield d @@ -110,17 +110,17 @@ abstract class DefaultDocDriver extends DocDriver with ModelFrames with ModelToX new ListClassFrame with Frame { def title = "List of classes and objects in package " + pkg0.fullName('.') - def classes = classes0; - def path = pkgPath(pkg0.sym) + NAME_SUFFIX_PACKAGE; - def navLabel = pkg0.fullName('.'); + def classes = classes0 + def path = pkgPath(pkg0.sym) + NAME_SUFFIX_PACKAGE + def navLabel = pkg0.fullName('.') } new PackageContentFrame with Frame { - def classes = classes0; - def pkg = pkg0; + def classes = classes0 + def pkg = pkg0 } for (clazz0 <- classes0) { new ClassContentFrame with Frame { - def clazz = clazz0; + def clazz = clazz0 def title = clazz0.kind + " " + clazz0.name + " in " + (clazz0.sym.owner.fullNameString('.')); } @@ -190,7 +190,7 @@ abstract class DefaultDocDriver extends DocDriver with ModelFrames with ModelToX override protected def decodeOption(tag: String, option: String): NodeSeq = tag match { case "throws" if additions0.exceptions.contains(option) => - val (sym, s) = additions0.exceptions(option); + val (sym, s) = additions0.exceptions(option) val path = "../" //todo: fix path val href = path + sym.fullNameString('/') + (if (sym.isModule || sym.isModuleClass) NAME_SUFFIX_OBJECT else "") + diff --git a/src/compiler/scala/tools/nsc/doc/ModelAdditions.scala b/src/compiler/scala/tools/nsc/doc/ModelAdditions.scala index 47fc476846..012c7d14e9 100644 --- a/src/compiler/scala/tools/nsc/doc/ModelAdditions.scala +++ b/src/compiler/scala/tools/nsc/doc/ModelAdditions.scala @@ -7,199 +7,195 @@ package scala.tools.nsc.doc /** - * @author Sean McDirmid + * @author Stephane Micheloud, Sean McDirmid * @version 1.0 */ -class ModelAdditions(val global : Global) { - import global._; - import definitions._; - def addition(sym : global.Symbol) : Unit = {} +class ModelAdditions(val global: Global) { + import global._ + import definitions._ + def addition(sym: global.Symbol) {} addition(AllClass); comments(AllClass) = """ - /** <p> - * Class <code>Nothing</code> (previously named <code>All</code> in - * <a href="http://scala-lang.org" target="_top">Scala</a> 2.2.0 and - * older versions) is - together with class <a href="Null.html"> - * <code>Null</code></a> - at the bottom of the - * <a href="http://scala-lang.org" target="_top">Scala</a> type - * hierarchy. - * </p> - * <p> - * Type <code>Nothing</code> is a subtype of every other type - * (including <a href="Null.html"><code>Null</code></a>); there - * exist <em>no instances</em> of this type. Even though type - * <code>Nothing</code> is empty, it is nevertheless useful as a - * type parameter. For instance, the <a href="http://scala-lang.org" - * target="_top">Scala</a> library defines a value - * <a href="Nil$object.html"><code>Nil</code></a> of type - * <code><a href="List.html">List</a>[Nothing]</code>. Because lists - * are covariant in <a href="http://scala-lang.org" target="_top">Scala</a>, - * this makes <a href="Nil$object.html"><code>Nil</code></a> an - * instance of <code><a href="List.html">List</a>[T]</code>, for - * any element type <code>T</code>. - * </p> - */"""; + <p> + Class <code>Nothing</code> (previously named <code>All</code> in + <a href="http://scala-lang.org" target="_top">Scala</a> 2.2.0 and + older versions) is - together with class <a href="Null.html"> + <code>Null</code></a> - at the bottom of the + <a href="http://scala-lang.org" target="_top">Scala</a> type + hierarchy. + </p> + <p> + Type <code>Nothing</code> is a subtype of every other type + (including <a href="Null.html"><code>Null</code></a>); there + exist <em>no instances</em> of this type. Even though type + <code>Nothing</code> is empty, it is nevertheless useful as a + type parameter. For instance, the <a href="http://scala-lang.org" + target="_top">Scala</a> library defines a value + <a href="Nil$object.html"><code>Nil</code></a> of type + <code><a href="List.html">List</a>[Nothing]</code>. Because lists + are covariant in <a href="http://scala-lang.org" target="_top">Scala</a>, + this makes <a href="Nil$object.html"><code>Nil</code></a> an + instance of <code><a href="List.html">List</a>[T]</code>, for + any element type <code>T</code>. + </p>""" + addition(AllRefClass); comments(AllRefClass) = """ - /** <p> - * Class <code>Null</code> (previously named <code>AllRef</code> in - * <a href="http://scala-lang.org" target="_top">Scala</a> 2.2.0 and - * older versions) is - together with class <a href="Nothing.html"> - * <code>Nothing</code> - at the bottom of the - * <a href="http://scala-lang.org" target="_top">Scala</a> type - * hierarchy. - * </p> - * <p> - * Type <code>Null</code> is a subtype of all reference types; its - * only instance is the <code>null</code> reference. - * Since <code>Null</code> is not a subtype of value types, - * <code>null</code> is not a member of any such type. For instance, - * it is not possible to assign <code>null</code> to a variable of - * type <a href="Int.html"><code>Int</code></a>. - * </p> - */"""; + <p> + Class <code>Null</code> (previously named <code>AllRef</code> in + <a href="http://scala-lang.org" target="_top">Scala</a> 2.2.0 and + older versions) is - together with class <a href="Nothing.html"> + <code>Nothing</code> - at the bottom of the + <a href="http://scala-lang.org" target="_top">Scala</a> type + hierarchy. + </p> + <p> + Type <code>Null</code> is a subtype of all reference types; its + only instance is the <code>null</code> reference. + Since <code>Null</code> is not a subtype of value types, + <code>null</code> is not a member of any such type. For instance, + it is not possible to assign <code>null</code> to a variable of + type <a href="Int.html"><code>Int</code></a>. + </p>""" addition(AnyClass); comments(AnyClass) = """ - /** <p> - * Class <code>Any</code> is the root of the <a - * href="http://scala-lang.org/" - * target="_top">Scala</a> class hierarchy. Every class in a - * <a href="http://scala-lang.org/" target="_top">Scala</a> execution - * environment inherits directly or indirectly from this class. - * Class <code>Any</code> has two direct subclasses: - * <a href="AnyRef.html"><code>AnyRef</code></a> and - * <a href="AnyVal.html"><code>AnyVal</code></a>. - * </p> - */"""; - /****/ - addition(Object_isInstanceOf); + <p> + Class <code>Any</code> is the root of the <a + href="http://scala-lang.org/" + target="_top">Scala</a> class hierarchy. Every class in a + <a href="http://scala-lang.org/" target="_top">Scala</a> execution + environment inherits directly or indirectly from this class. + Class <code>Any</code> has two direct subclasses: + <a href="AnyRef.html"><code>AnyRef</code></a> and + <a href="AnyVal.html"><code>AnyVal</code></a>. + </p>""" + addition(Object_isInstanceOf); comments(Object_isInstanceOf) = """ - /** <p> - * The method <code>isInstanceOf</code> is the pendant of the Java - * operator <code>instanceof</code>. - * </p> - * @see <ul><li>Java Language Specification (2<sup>nd</sup> Ed.): - * <a href="http://java.sun.com/docs/books/jls/second_edition/html/expressions.doc.html#80289" - * target="_top">Operator <code>instanceof</code></a>.</li></ul> - */"""; - /****/ + <p> + The method <code>isInstanceOf</code> is the pendant of the Java + operator <code>instanceof</code>. + </p> + @see <ul><li>Java Language Specification (2<sup>nd</sup> Ed.): + <a href="http://java.sun.com/docs/books/jls/second_edition/html/expressions.doc.html#80289" + target="_top">Operator <code>instanceof</code></a>.</li></ul> + """ + addition(Object_synchronized); comments(Object_synchronized) = """ - /** <p> - * To make your programs thread-safe, you must first identify what - * data will be shared across threads. If you are writing data that - * may be read later by another thread, or reading data that may - * have been written by another thread, then that data is shared, - * and you must synchronize when accessing it. - * </p> - * @see <ul><li>The Java Tutorials: - * <a href="http://java.sun.com/docs/books/tutorial/essential/concurrency/sync.html" - * target="_top">Synchronization</a>.</li> - * <li> IBM developerWorks: - * <a href="http://www-128.ibm.com/developerworks/java/library/j-threads1.html" - * target="_top">Synchronization is not the enemy</a>.</li></ul> - */"""; + <p> + To make your programs thread-safe, you must first identify what + data will be shared across threads. If you are writing data that + may be read later by another thread, or reading data that may + have been written by another thread, then that data is shared, + and you must synchronize when accessing it. + </p> + @see <ul><li>The Java Tutorials: + <a href="http://java.sun.com/docs/books/tutorial/essential/concurrency/sync.html" + target="_top">Synchronization</a>.</li> + <li> IBM developerWorks: + <a href="http://www-128.ibm.com/developerworks/java/library/j-threads1.html" + target="_top">Synchronization is not the enemy</a>.</li></ul> + """ + addition(AnyRefClass); comments(AnyRefClass) = """ - /** <p> - * Class <code>AnyRef</code> is the root class of all - * <em>reference types</em>. - * </p> - */"""; + <p> + Class <code>AnyRef</code> is the root class of all + <em>reference types</em>. + </p>""" + addition(AnyValClass); comments(AnyValClass) = """ - /** <p> - * Class <code>AnyVal</code> is the root class of all - * <em>value types</em>. - * </p> - * <p> - * <code>AnyVal</code> has a fixed number subclasses, which - * describe values which are not implemented as objects in the - * underlying host system. - * </p> - * <p> - * Classes <a href="Double.html"><code>Double</code></a>, - * <a href="Float.html"><code>Float</code></a>, - * <a href="Long.html"><code>Long</code></a>, - * <a href="Int.html"><code>Int</code></a>, - * <a href="Char.html"><code>Char</code></a>, - * <a href="Short.html"><code>Short</code></a>, and - * <a href="Byte.html"><code>Byte</code></a> are together called - * <em>numeric value types</em>. - * Classes <a href="Byte.html"><code>Byte</code></a>, - * <a href="Short.html"><code>Short</code></a>, or - * <a href="Char.html"><code>Char</code></a> - * are called <em>subrange types</em>. Subrange types, as well as - * <a href="Int.html"><code>Int</code></a> and - * <a href="Long.html"><code>Long</code></a> are called - * <em>integer types</em>, whereas - * <a href="Float.html"><code>Float</code></a> and - * <a href="Double.html"><code>Double</code></a> are called - * <em>floating point types</em>. - * </p> - */"""; - addition(BooleanClass); - comments(BooleanClass) = {""" - /** <p> - * Class <code>Boolean</code> has only two values: <code>true</code> - * and <code>false</code>. - * </p> - */"""}; + <p> + Class <code>AnyVal</code> is the root class of all + <em>value types</em>. + </p> + <p> + <code>AnyVal</code> has a fixed number subclasses, which + describe values which are not implemented as objects in the + underlying host system. + </p> + <p> + Classes <a href="Double.html"><code>Double</code></a>, + <a href="Float.html"><code>Float</code></a>, + <a href="Long.html"><code>Long</code></a>, + <a href="Int.html"><code>Int</code></a>, + <a href="Char.html"><code>Char</code></a>, + <a href="Short.html"><code>Short</code></a>, and + <a href="Byte.html"><code>Byte</code></a> are together called + <em>numeric value types</em>. + Classes <a href="Byte.html"><code>Byte</code></a>, + <a href="Short.html"><code>Short</code></a>, or + <a href="Char.html"><code>Char</code></a> + are called <em>subrange types</em>. Subrange types, as well as + <a href="Int.html"><code>Int</code></a> and + <a href="Long.html"><code>Long</code></a> are called + <em>integer types</em>, whereas + <a href="Float.html"><code>Float</code></a> and + <a href="Double.html"><code>Double</code></a> are called + <em>floating point types</em>. + </p>""" + + addition(BooleanClass) + comments(BooleanClass) = """ + <p> + Class <code>Boolean</code> has only two values: <code>true</code> + and <code>false</code>. + </p>""" + def numericValDescr(sym: Symbol) = { val maxValue = "MAX_" + sym.name.toString().toUpperCase() - val minValue = "MIN_" + sym.name.toString().toUpperCase(); - addition(sym); + val minValue = "MIN_" + sym.name.toString().toUpperCase() + addition(sym) comments(sym) = """ - /** <p> - * Class <code>""" + sym.name + """ </code> belongs to the value - * classes whose instances are not represented as objects by the - * underlying host system. All value classes inherit from class - * <a href="AnyVal.html"><code>AnyVal</code></a>. - * </p> - * <p> - * Values <code>""" + maxValue + """</code> and <code>""" + minValue + """</code> - * are in defined in object <a href="Math$object.html">scala.Math</a>. - * </p> - */"""; + <p> + Class <code>""" + sym.name + """ </code> belongs to the value + classes whose instances are not represented as objects by the + underlying host system. All value classes inherit from class + <a href="AnyVal.html"><code>AnyVal</code></a>. + </p> + <p> + Values <code>""" + maxValue + """</code> and <code>""" + minValue + """</code> + are in defined in object <a href="Math$object.html">scala.Math</a>. + </p>""" } (ByteClass :: CharClass :: DoubleClass :: LongClass :: FloatClass :: IntClass :: ShortClass :: Nil).foreach(numericValDescr); addition(UnitClass); - comments(UnitClass) = {""" - /** <p> - * Class <code>Unit</code> has only one value: <code>()</code>. - * </p> - */"""}; - addition(UnitClass); + comments(UnitClass) = """ + <p> + Class <code>Unit</code> has only one value: <code>()</code>. + </p>""" - def boxedValDescr(what : String) = { - val sym = definitions.getClass("java.lang." + what); - addition(sym); + addition(UnitClass); +/* + def boxedValDescr(what: String) = { + val sym = definitions.getClass("java.lang." + what) + addition(sym) comments(sym) = """ - /** <p> - * Class <code>""" + sym.name + """</code> implements the - * boxing/unboxing from/to value types. - * </p> - * <p> - * Boxing and unboxing enable value types to be treated as objects; - * they provide a unified view of the type system wherein a value - * of any type can ultimately be treated as an object. - * </p> - */""" + <p> + Class <code>""" + sym.name + """</code> implements the + boxing/unboxing from/to value types. + </p> + <p> + Boxing and unboxing enable value types to be treated as objects; + they provide a unified view of the type system wherein a value + of any type can ultimately be treated as an object. + </p>""" }; //("Float" :: "Long" :: "Number" :: "Integer" :: Nil).foreach(boxedValDescr); - +*/ object exceptions extends collection.jcl.TreeMap[String,(Symbol,String)] { - def f(name : String) = { - this("Predef." + name) = (definitions.PredefModule, name); + def f(name: String) { + this("Predef." + name) = (definitions.PredefModule, name) } - f("IndexOutOfBoundsException"); - f("NoSuchElementException"); - f("NullPointerException"); - f("UnsupportedOperationException"); + f("IndexOutOfBoundsException") + f("NoSuchElementException") + f("NullPointerException") + f("UnsupportedOperationException") } } diff --git a/src/library/scala/StringBuilder.scala b/src/library/scala/StringBuilder.scala index 116ec53490..8b657c3279 100644 --- a/src/library/scala/StringBuilder.scala +++ b/src/library/scala/StringBuilder.scala @@ -541,9 +541,35 @@ extends (Int => Char) with Proxy { this } + /** <p> + * Inserts the string representation of the <code>Boolean</code> argument + * into this sequence. + * </p> + * <p> + * The offset argument must be greater than or equal to 0, and less than + * or equal to the length of this sequence. + * </p> + * + * @param at the offset position. + * @param x a <code>Boolean</code> value. + * @return a reference to this object. + */ def insert(at: Int, x: Boolean): StringBuilder = insert(at, String.valueOf(x)) + /** <p> + * Inserts the string representation of the <code>Char</code> argument + * into this sequence. + * </p> + * <p> + * The offset argument must be greater than or equal to 0, and less than + * or equal to the length of this sequence. + * </p> + * + * @param at the offset position. + * @param x a <code>Char</code> value. + * @return a reference to this object. + */ def insert(at: Int, x: Char): StringBuilder = { if (at < 0 || at > count) throw new StringIndexOutOfBoundsException(at) @@ -555,25 +581,81 @@ extends (Int => Char) with Proxy { this } + /** <p> + * Inserts the string representation of the <code>Int</code> argument + * into this sequence. + * </p> + * <p> + * The offset argument must be greater than or equal to 0, and less than + * or equal to the length of this sequence. + * </p> + * + * @param at the offset position. + * @param x a <code>Int</code> value. + * @return a reference to this object. + */ def insert(at: Int, x: Int): StringBuilder = insert(at, String.valueOf(x)) + /** <p> + * Inserts the string representation of the <code>Long</code> argument + * into this sequence. + * </p> + * <p> + * The offset argument must be greater than or equal to 0, and less than + * or equal to the length of this sequence. + * </p> + * + * @param at the offset position. + * @param x a <code>Long</code> value. + * @return a reference to this object. + */ def insert(at: Int, x: Long): StringBuilder = insert(at, String.valueOf(x)) + /** <p> + * Inserts the string representation of the <code>Float</code> argument + * into this sequence. + * </p> + * <p> + * The offset argument must be greater than or equal to 0, and less than + * or equal to the length of this sequence. + * </p> + * + * @param at the offset position. + * @param x a <code>Float</code> value. + * @return a reference to this object. + */ def insert(at: Int, x: Float): StringBuilder = insert(at, String.valueOf(x)) + /** <p> + * Inserts the string representation of the <code>Double</code> argument + * into this sequence. + * </p> + * <p> + * The offset argument must be greater than or equal to 0, and less than + * or equal to the length of this sequence. + * </p> + * + * @param at the offset position. + * @param x a <code>Double</code> value. + * @return a reference to this object. + */ def insert(at: Int, x: Double): StringBuilder = insert(at, String.valueOf(x)) - /** Returns the index within this string of the first occurrence of the - * specified substring. The integer returned is the smallest value - * <i>k</i> such that: + /** <p> + * Returns the index within this string of the first occurrence of the + * specified substring. The integer returned is the smallest value + * <i>k</i> such that: + * </p> * <blockquote><pre> - * this.toString().startsWith(str, <i>k</i>) - * </pre></blockquote> - * is <code>true</code>. + * this.toString().startsWith(str, <i>k</i>)</pre> + * </blockquote> + * <p> + * is <code>true</code>. + * </p> * * @param str any string. * @return if the string argument occurs as a substring within this @@ -584,17 +666,38 @@ extends (Int => Char) with Proxy { */ def indexOf(str: String): Int = indexOf(str, 0) + /** <p> + * Returns the index within this string of the first occurrence of the + * specified substring, starting at the specified index. The integer + * returned is the smallest value <code>k</code> for which: + * </p><pre> + * k >= Math.min(fromIndex, str.length()) && + * this.toString().startsWith(str, k)</pre> + * <p> + * If no such value of <code>k</code> exists, then <code>-1</code> + * is returned. + * </p> + * + * @param str the substring for which to search. + * @param fromIndex the index from which to start the search. + * @return the index within this string of the first occurrence + * of the specified substring, starting at the specified index. + */ def indexOf(str: String, fromIndex: Int): Int = StringBuilder.indexOf(value, 0, count, str.toCharArray, 0, str.length(), fromIndex) - /** Returns the index within this string of the rightmost occurrence - * of the specified substring. The rightmost empty string "" is - * considered to occur at the index value <code>this.length()</code>. - * The returned index is the largest value <i>k</i> such that + /** <p> + * Returns the index within this string of the rightmost occurrence + * of the specified substring. The rightmost empty string "" is + * considered to occur at the index value <code>this.length()</code>. + * The returned index is the largest value <i>k</i> such that + * </p> * <blockquote><pre> - * this.toString().startsWith(str, k) - * </pre></blockquote> - * is true. + * this.toString().startsWith(str, k)</pre> + * </blockquote> + * <p> + * is true. + * </p> * * @param str the substring to search for. * @return if the string argument occurs one or more times as a substring @@ -605,6 +708,23 @@ extends (Int => Char) with Proxy { */ def lastIndexOf(str: String): Int = lastIndexOf(str, count) + /** <p> + * Returns the index within this string of the last occurrence of the + * specified substring. The integer returned is the largest value + * <code>k</code> such that: + * </p><pre> + * k <= Math.min(fromIndex, str.length()) && + * this.toString().startsWith(str, k)</pre> + * <p> + * If no such value of <code>k</code> exists, then <code>-1</code> + * is returned. + * </p> + * + * @param str the substring to search for. + * @param fromIndex the index to start the search from. + * @return the index within this sequence of the last occurrence + * of the specified substring. + */ def lastIndexOf(str: String, fromIndex: Int): Int = StringBuilder.lastIndexOf(value, 0, count, str.toCharArray, 0, str.length(), fromIndex) |