From 2d39db44e2f74571fa4dd407f5f56fb568b37360 Mon Sep 17 00:00:00 2001 From: michelou Date: Mon, 25 Feb 2008 17:34:15 +0000 Subject: fixed scaladoc comments --- .../scala/tools/nsc/doc/DefaultDocDriver.scala | 20 +- .../scala/tools/nsc/doc/ModelAdditions.scala | 320 ++++++++++----------- 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) = """ - /**

- * Class Nothing (previously named All in - * Scala 2.2.0 and - * older versions) is - together with class - * Null - at the bottom of the - * Scala type - * hierarchy. - *

- *

- * Type Nothing is a subtype of every other type - * (including Null); there - * exist no instances of this type. Even though type - * Nothing is empty, it is nevertheless useful as a - * type parameter. For instance, the Scala library defines a value - * Nil of type - * List[Nothing]. Because lists - * are covariant in Scala, - * this makes Nil an - * instance of List[T], for - * any element type T. - *

- */"""; +

+ Class Nothing (previously named All in + Scala 2.2.0 and + older versions) is - together with class + Null - at the bottom of the + Scala type + hierarchy. +

+

+ Type Nothing is a subtype of every other type + (including Null); there + exist no instances of this type. Even though type + Nothing is empty, it is nevertheless useful as a + type parameter. For instance, the Scala library defines a value + Nil of type + List[Nothing]. Because lists + are covariant in Scala, + this makes Nil an + instance of List[T], for + any element type T. +

""" + addition(AllRefClass); comments(AllRefClass) = """ - /**

- * Class Null (previously named AllRef in - * Scala 2.2.0 and - * older versions) is - together with class - * Nothing - at the bottom of the - * Scala type - * hierarchy. - *

- *

- * Type Null is a subtype of all reference types; its - * only instance is the null reference. - * Since Null is not a subtype of value types, - * null is not a member of any such type. For instance, - * it is not possible to assign null to a variable of - * type Int. - *

- */"""; +

+ Class Null (previously named AllRef in + Scala 2.2.0 and + older versions) is - together with class + Nothing - at the bottom of the + Scala type + hierarchy. +

+

+ Type Null is a subtype of all reference types; its + only instance is the null reference. + Since Null is not a subtype of value types, + null is not a member of any such type. For instance, + it is not possible to assign null to a variable of + type Int. +

""" addition(AnyClass); comments(AnyClass) = """ - /**

- * Class Any is the root of the Scala class hierarchy. Every class in a - * Scala execution - * environment inherits directly or indirectly from this class. - * Class Any has two direct subclasses: - * AnyRef and - * AnyVal. - *

- */"""; - /****/ - addition(Object_isInstanceOf); +

+ Class Any is the root of the Scala class hierarchy. Every class in a + Scala execution + environment inherits directly or indirectly from this class. + Class Any has two direct subclasses: + AnyRef and + AnyVal. +

""" + addition(Object_isInstanceOf); comments(Object_isInstanceOf) = """ - /**

- * The method isInstanceOf is the pendant of the Java - * operator instanceof. - *

- * @see - */"""; - /****/ +

+ The method isInstanceOf is the pendant of the Java + operator instanceof. +

+ @see + """ + addition(Object_synchronized); comments(Object_synchronized) = """ - /**

- * 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. - *

- * @see - */"""; +

+ 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. +

+ @see + """ + addition(AnyRefClass); comments(AnyRefClass) = """ - /**

- * Class AnyRef is the root class of all - * reference types. - *

- */"""; +

+ Class AnyRef is the root class of all + reference types. +

""" + addition(AnyValClass); comments(AnyValClass) = """ - /**

- * Class AnyVal is the root class of all - * value types. - *

- *

- * AnyVal has a fixed number subclasses, which - * describe values which are not implemented as objects in the - * underlying host system. - *

- *

- * Classes Double, - * Float, - * Long, - * Int, - * Char, - * Short, and - * Byte are together called - * numeric value types. - * Classes Byte, - * Short, or - * Char - * are called subrange types. Subrange types, as well as - * Int and - * Long are called - * integer types, whereas - * Float and - * Double are called - * floating point types. - *

- */"""; - addition(BooleanClass); - comments(BooleanClass) = {""" - /**

- * Class Boolean has only two values: true - * and false. - *

- */"""}; +

+ Class AnyVal is the root class of all + value types. +

+

+ AnyVal has a fixed number subclasses, which + describe values which are not implemented as objects in the + underlying host system. +

+

+ Classes Double, + Float, + Long, + Int, + Char, + Short, and + Byte are together called + numeric value types. + Classes Byte, + Short, or + Char + are called subrange types. Subrange types, as well as + Int and + Long are called + integer types, whereas + Float and + Double are called + floating point types. +

""" + + addition(BooleanClass) + comments(BooleanClass) = """ +

+ Class Boolean has only two values: true + and false. +

""" + 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) = """ - /**

- * Class """ + sym.name + """ belongs to the value - * classes whose instances are not represented as objects by the - * underlying host system. All value classes inherit from class - * AnyVal. - *

- *

- * Values """ + maxValue + """ and """ + minValue + """ - * are in defined in object scala.Math. - *

- */"""; +

+ Class """ + sym.name + """ belongs to the value + classes whose instances are not represented as objects by the + underlying host system. All value classes inherit from class + AnyVal. +

+

+ Values """ + maxValue + """ and """ + minValue + """ + are in defined in object scala.Math. +

""" } (ByteClass :: CharClass :: DoubleClass :: LongClass :: FloatClass :: IntClass :: ShortClass :: Nil).foreach(numericValDescr); addition(UnitClass); - comments(UnitClass) = {""" - /**

- * Class Unit has only one value: (). - *

- */"""}; - addition(UnitClass); + comments(UnitClass) = """ +

+ Class Unit has only one value: (). +

""" - 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) = """ - /**

- * Class """ + sym.name + """ implements the - * boxing/unboxing from/to value types. - *

- *

- * 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. - *

- */""" +

+ Class """ + sym.name + """ implements the + boxing/unboxing from/to value types. +

+

+ 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. +

""" }; //("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 } + /**

+ * Inserts the string representation of the Boolean argument + * into this sequence. + *

+ *

+ * The offset argument must be greater than or equal to 0, and less than + * or equal to the length of this sequence. + *

+ * + * @param at the offset position. + * @param x a Boolean value. + * @return a reference to this object. + */ def insert(at: Int, x: Boolean): StringBuilder = insert(at, String.valueOf(x)) + /**

+ * Inserts the string representation of the Char argument + * into this sequence. + *

+ *

+ * The offset argument must be greater than or equal to 0, and less than + * or equal to the length of this sequence. + *

+ * + * @param at the offset position. + * @param x a Char 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 } + /**

+ * Inserts the string representation of the Int argument + * into this sequence. + *

+ *

+ * The offset argument must be greater than or equal to 0, and less than + * or equal to the length of this sequence. + *

+ * + * @param at the offset position. + * @param x a Int value. + * @return a reference to this object. + */ def insert(at: Int, x: Int): StringBuilder = insert(at, String.valueOf(x)) + /**

+ * Inserts the string representation of the Long argument + * into this sequence. + *

+ *

+ * The offset argument must be greater than or equal to 0, and less than + * or equal to the length of this sequence. + *

+ * + * @param at the offset position. + * @param x a Long value. + * @return a reference to this object. + */ def insert(at: Int, x: Long): StringBuilder = insert(at, String.valueOf(x)) + /**

+ * Inserts the string representation of the Float argument + * into this sequence. + *

+ *

+ * The offset argument must be greater than or equal to 0, and less than + * or equal to the length of this sequence. + *

+ * + * @param at the offset position. + * @param x a Float value. + * @return a reference to this object. + */ def insert(at: Int, x: Float): StringBuilder = insert(at, String.valueOf(x)) + /**

+ * Inserts the string representation of the Double argument + * into this sequence. + *

+ *

+ * The offset argument must be greater than or equal to 0, and less than + * or equal to the length of this sequence. + *

+ * + * @param at the offset position. + * @param x a Double 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 - * k such that: + /**

+ * Returns the index within this string of the first occurrence of the + * specified substring. The integer returned is the smallest value + * k such that: + *

* 
-   *  this.toString().startsWith(str, k)
-   *
- * is true. + * this.toString().startsWith(str, k) + * + *

+ * is true. + *

* * @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) + /**

+ * 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 k for which: + * 

+   *    k >= Math.min(fromIndex, str.length()) &&
+   *                   this.toString().startsWith(str, k)
+ *

+ * If no such value of k exists, then -1 + * is returned. + *

+ * + * @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 this.length(). - * The returned index is the largest value k such that + /**

+ * 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 this.length(). + * The returned index is the largest value k such that + *

* 
-   *  this.toString().startsWith(str, k)
-   *
- * is true. + * this.toString().startsWith(str, k) + * + *

+ * is true. + *

* * @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) + /**

+ * Returns the index within this string of the last occurrence of the + * specified substring. The integer returned is the largest value + * k such that: + * 

+   *    k <= Math.min(fromIndex, str.length()) &&
+   *                   this.toString().startsWith(str, k)
+ *

+ * If no such value of k exists, then -1 + * is returned. + *

+ * + * @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) -- cgit v1.2.3