diff options
-rw-r--r-- | src/compiler/scala/tools/nsc/Interpreter.scala | 103 | ||||
-rw-r--r-- | src/compiler/scala/tools/nsc/doc/DocGenerator.scala | 30 | ||||
-rw-r--r-- | src/library/scala/BigInt.scala | 24 | ||||
-rw-r--r-- | src/library/scala/xml/Parsing.scala | 111 | ||||
-rw-r--r-- | src/manual/scala/man1/scaladoc.scala | 28 |
5 files changed, 173 insertions, 123 deletions
diff --git a/src/compiler/scala/tools/nsc/Interpreter.scala b/src/compiler/scala/tools/nsc/Interpreter.scala index 749a5ef1d8..c4a70304d0 100644 --- a/src/compiler/scala/tools/nsc/Interpreter.scala +++ b/src/compiler/scala/tools/nsc/Interpreter.scala @@ -18,33 +18,40 @@ import reporters.{ConsoleReporter, Reporter} import symtab.Flags import util.SourceFile -/** An interpreter for Scala code. - - The main public entry points are compile() and interpret(). The compile() - method loads a complete Scala file. The interpret() method executes one - line of Scala code at the request of the user. - - The overall approach is based on compiling the requested code and then - using a Java classloader and Java reflection to run the code - and access its results. - - In more detail, a single compiler instance is used - to accumulate all successfully compiled or interpreted Scala code. To - "interpret" a line of code, the compiler generates a fresh object that - includes the line of code and which has public member(s) to export - all variables defined by that code. To extract the result of an - interpreted line to show the user, a second "result object" is created - which imports the variables exported by the above object and then - exports a single member named "result". To accomodate user expressions - that read from variables or methods defined in previous statements, "import" - statements are used. - - This interpreter shares the strengths and weaknesses of using the - full compiler-to-Java. The main strength is that interpreted code - behaves exactly as does compiled code, including running at full speed. - The main weakness is that redefining classes and methods is not handled - properly, because rebinding at the Java level is technically difficult. -*/ +/** <p> + * An interpreter for Scala code. + * </p> + * <p> + * The main public entry points are <code>compile()</code> and + * <code>interpret()</code>. The <code>compile()</code> method loads a + * complete Scala file. The <code>interpret()</code> method executes one + * line of Scala code at the request of the user. + * </p> + * <p> + * The overall approach is based on compiling the requested code and then + * using a Java classloader and Java reflection to run the code + * and access its results. + * </p> + * <p> + * In more detail, a single compiler instance is used + * to accumulate all successfully compiled or interpreted Scala code. To + * "interpret" a line of code, the compiler generates a fresh object that + * includes the line of code and which has public member(s) to export + * all variables defined by that code. To extract the result of an + * interpreted line to show the user, a second "result object" is created + * which imports the variables exported by the above object and then + * exports a single member named "result". To accomodate user expressions + * that read from variables or methods defined in previous statements, "import" + * statements are used. + * </p> + * <p> + * This interpreter shares the strengths and weaknesses of using the + * full compiler-to-Java. The main strength is that interpreted code + * behaves exactly as does compiled code, including running at full speed. + * The main weakness is that redefining classes and methods is not handled + * properly, because rebinding at the Java level is technically difficult. + * </p> + */ class Interpreter(val settings: Settings, reporter: Reporter, out: PrintWriter) { import symtab.Names import compiler.Traverser @@ -246,12 +253,16 @@ class Interpreter(val settings: Settings, reporter: Reporter, out: PrintWriter) } } - /** Interpret one line of input. All feedback, including parse errors - * and evaluation results, are printed via the supplied compiler's - * reporter. Values defined are available for future interpreted - * strings. - * The return value is whether the line was interpreter successfully, - * e.g. that there were no parse errors. + /** <p> + * Interpret one line of input. All feedback, including parse errors + * and evaluation results, are printed via the supplied compiler's + * reporter. Values defined are available for future interpreted + * strings. + * </p> + * <p> + * The return value is whether the line was interpreter successfully, + * e.g. that there were no parse errors. + * </p> * * @param line ... * @return ... @@ -348,13 +359,16 @@ class Interpreter(val settings: Settings, reporter: Reporter, out: PrintWriter) } - /** This instance is no longer needed, so release any resources - it is using. - - Specifically, this deletes the temporary directory used for holding - class files for this instance. This cannot safely be done after - each command is executed because of Java's demand loading. - */ + /** <p> + * This instance is no longer needed, so release any resources + * it is using. + * </p> + * <p> + * Specifically, this deletes the temporary directory used for holding + * class files for this instance. This cannot safely be done after + * each command is executed because of Java's demand loading. + * </p> + */ def close: Unit = Interpreter.deleteRecursively(classfilePath) @@ -648,8 +662,14 @@ class Interpreter(val settings: Settings, reporter: Reporter, out: PrintWriter) } } +/** The object <code>Interpreter</code> ... + */ object Interpreter { - /** Delete a directory tree recursively. Use with care! */ + + /** Delete a directory tree recursively. Use with care! + * + * @param path ... + */ def deleteRecursively(path: File): Unit = { path match { case _ if (!path.exists) => () @@ -660,4 +680,5 @@ object Interpreter { case _ => path.delete } } + } diff --git a/src/compiler/scala/tools/nsc/doc/DocGenerator.scala b/src/compiler/scala/tools/nsc/doc/DocGenerator.scala index 8153e5f293..fd9699d551 100644 --- a/src/compiler/scala/tools/nsc/doc/DocGenerator.scala +++ b/src/compiler/scala/tools/nsc/doc/DocGenerator.scala @@ -126,7 +126,7 @@ abstract class DocGenerator extends Models { save(page(title, body, hasBody)) } - val doctitle: NodeSeq = + private val doctitle: NodeSeq = <div class="doctitle-larger"> {load(documentTitle)} </div>; @@ -654,22 +654,30 @@ abstract class DocGenerator extends Models { //http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html#javadoctags //http://java.sun.com/j2se/javadoc/writingdoccomments/ + //REMINDER: update file "src/manual/scala/man1/scaladoc.scala" accordingly! private def tag(name: String): NodeSeq = <b> { Text((name match { - case "author" => "Author" - case "exception" => "Throws" - case "param" => "Parameters" - case "return" => "Returns" - case "see" => "See Also" - case "since" => "Since" - case "throws" => "Throws" - case "todo" => "Todo" - case "version" => "Version" + case "author" => "Author" + case "deprecated" => "Deprecated" + case "exception" => "Throws" + case "param" => "Parameters" + case "return" => "Returns" + case "see" => "See Also" + case "since" => "Since" + case "throws" => "Throws" + case "todo" => "Todo" + case "version" => "Version" case _ => name }) + ":") } </b> + // patterns for standard tags with 1 and 2 arguments + private val pat1 = Pattern.compile( + "[ \t]*@(author|deprecated|return|see|since|todo|version)[ \t]+(.*)") + private val pat2 = Pattern.compile( + "[ \t]*@(exception|param|throws)[ \t]+(\\p{Alnum}*)[ \t]+(.*)") + def comment(comment: String, isShort: Boolean): NodeSeq = { var ret: List[Node] = Nil assert(comment != null) @@ -683,8 +691,6 @@ abstract class DocGenerator extends Models { type AttrDescr = Triple[String, String, StringBuffer] val attributes = new ListBuffer[AttrDescr] var attr: AttrDescr = null - val pat1 = Pattern.compile("[ \t]*@(author|return|see|since|todo|version)[ \t]+(.*)") - val pat2 = Pattern.compile("[ \t]*@(exception|param|throws)[ \t]+(\\p{Alnum}*)[ \t]+(.*)") val tok = new StringTokenizer(comment0, LINE_SEPARATOR) while (tok.hasMoreTokens) { val s = tok.nextToken.replaceFirst("\\p{Space}?\\*", "") diff --git a/src/library/scala/BigInt.scala b/src/library/scala/BigInt.scala index be2d00d5e5..8efad433b1 100644 --- a/src/library/scala/BigInt.scala +++ b/src/library/scala/BigInt.scala @@ -109,6 +109,10 @@ object BigInt { } } +/** + * @author Martin Odersky + * @version 1.0, 15/07/2003 + */ [serializable] class BigInt(val bigInteger: BigInteger) extends runtime.BoxedNumber { @@ -312,28 +316,32 @@ class BigInt(val bigInteger: BigInteger) extends runtime.BoxedNumber { def charValue = intValue.toChar /** Converts this BigInt to an <tt>int</tt>. - * If the BigInt is too big to fit in a char, only the low-order 32 bits are returned. - * Note that this conversion can lose information about the overall magnitude of the - * BigInt value as well as return a result with the opposite sign. + * If the BigInt is too big to fit in a char, only the low-order 32 bits + * are returned. Note that this conversion can lose information about the + * overall magnitude of the BigInt value as well as return a result with + * the opposite sign. */ def intValue = this.bigInteger.intValue /** Converts this BigInt to a <tt>long</tt>. - * If the BigInt is too big to fit in a char, only the low-order 64 bits are returned. - * Note that this conversion can lose information about the overall magnitude of the - * BigInt value as well as return a result with the opposite sign. + * If the BigInt is too big to fit in a char, only the low-order 64 bits + * are returned. Note that this conversion can lose information about the + * overall magnitude of the BigInt value as well as return a result with + * the opposite sign. */ def longValue = this.bigInteger.longValue /** Converts this BigInt to a <tt>float</tt>. * if this BigInt has too great a magnitude to represent as a float, - * it will be converted to Float.NEGATIVE_INFINITY or Float.POSITIVE_INFINITY as appropriate. + * it will be converted to <code>Float.NEGATIVE_INFINITY</code> or + * <code>Float.POSITIVE_INFINITY</code> as appropriate. */ def floatValue = this.bigInteger.floatValue /** Converts this BigInt to a <tt>double</tt>. * if this BigInt has too great a magnitude to represent as a float, - * it will be converted to Float.NEGATIVE_INFINITY or Float.POSITIVE_INFINITY as appropriate. + * it will be converted to <code>Float.NEGATIVE_INFINITY</code> or + * <code>Float.POSITIVE_INFINITY</code> as appropriate. */ def doubleValue = this.bigInteger.doubleValue diff --git a/src/library/scala/xml/Parsing.scala b/src/library/scala/xml/Parsing.scala index c19fb022f5..17bf4567b4 100644 --- a/src/library/scala/xml/Parsing.scala +++ b/src/library/scala/xml/Parsing.scala @@ -9,98 +9,97 @@ // $Id$ -package scala.xml; +package scala.xml -/** DEPRECATED - use either parsing.TokenTests, or Utilty (helper functions - * for parsing XML fragments ). +/** The object <code>Parsing</code> ... + * + * @author Burak Emir + * @version 1.0 + * + * @deprecated use either <code>parsing.TokenTests</code> or + * <code>Utilty</code> (helper functions for parsing XML fragments). */ object Parsing { - /** (#x20 | #x9 | #xD | #xA) */ - final def isSpace( ch:Char ):Boolean = ch match { + /** <pre>(#x20 | #x9 | #xD | #xA)</pre> */ + final def isSpace(ch: Char): Boolean = ch match { case '\u0009' | '\u000A' | '\u000D' | '\u0020' => true - case _ => false; + case _ => false } - /** (#x20 | #x9 | #xD | #xA)+ */ - final def isSpace( cs:Seq[Char] ):Boolean = { - val it = cs.elements; - it.hasNext && it.forall { isSpace }; + /** <pre>(#x20 | #x9 | #xD | #xA)+</pre> */ + final def isSpace(cs: Seq[Char]): Boolean = { + val it = cs.elements + it.hasNext && it.forall { isSpace } } - /** NameChar ::= Letter | Digit | '.' | '-' | '_' | ':' - * | CombiningChar | Extender + /** <pre>NameChar ::= Letter | Digit | '.' | '-' | '_' | ':' + * | CombiningChar | Extender</pre> * * see [4] and Appendix B of XML 1.0 specification - */ - def isNameChar( ch:Char ) = isNameStart( ch ) || (ch match { - case '.' | '-' | ':' => true; - case _ => java.lang.Character.getType( ch ).asInstanceOf[Byte] match { - case java.lang.Character.COMBINING_SPACING_MARK => true; // Mc - case java.lang.Character.ENCLOSING_MARK => true; // Me - case java.lang.Character.NON_SPACING_MARK => true; // Mn - case java.lang.Character.MODIFIER_LETTER => true; // Lm - case java.lang.Character.DECIMAL_DIGIT_NUMBER => true; // Nd - case _ => false; + */ + def isNameChar(ch: Char) = isNameStart(ch) || (ch match { + case '.' | '-' | ':' => true + case _ => java.lang.Character.getType(ch).asInstanceOf[Byte] match { + case java.lang.Character.COMBINING_SPACING_MARK => true // Mc + case java.lang.Character.ENCLOSING_MARK => true // Me + case java.lang.Character.NON_SPACING_MARK => true // Mn + case java.lang.Character.MODIFIER_LETTER => true // Lm + case java.lang.Character.DECIMAL_DIGIT_NUMBER => true // Nd + case _ => false } }); - /** NameStart ::= ( Letter | '_' ) + /** <pre>NameStart ::= ( Letter | '_' )</pre> * where Letter means in one of the Unicode general * categories { Ll, Lu, Lo, Lt, Nl } * * We do not allow a name to start with ':'. * see [3] and Appendix B of XML 1.0 specification */ - def isNameStart( ch:Char ) = - java.lang.Character.getType( ch ).asInstanceOf[Byte] match { - case java.lang.Character.LOWERCASE_LETTER => true; - case java.lang.Character.UPPERCASE_LETTER => true; - case java.lang.Character.OTHER_LETTER => true; - case java.lang.Character.TITLECASE_LETTER => true; - case java.lang.Character.LETTER_NUMBER => true; - case _ => ch match { - case '_' => true - case _ => false; - } + def isNameStart(ch: Char) = + java.lang.Character.getType(ch).asInstanceOf[Byte] match { + case java.lang.Character.LOWERCASE_LETTER => true + case java.lang.Character.UPPERCASE_LETTER => true + case java.lang.Character.OTHER_LETTER => true + case java.lang.Character.TITLECASE_LETTER => true + case java.lang.Character.LETTER_NUMBER => true + case _ => ch == '_' } - /** Name ::= ( Letter | '_' ) (NameChar)* + /** <pre>Name ::= ( Letter | '_' ) (NameChar)*</pre> * * see [5] of XML 1.0 specification */ - def isName( s:String ): Boolean = { - if( s.length() > 0 ) { - val z:Seq[Char] = s; - val y = z.elements; - if( isNameStart( y.next ) ) { - while( y.hasNext && isNameChar( y.next ) ) {}; + def isName(s: String): Boolean = + if (s.length() > 0) { + val z: Seq[Char] = s + val y = z.elements + if (isNameStart(y.next)) { + while (y.hasNext && isNameChar(y.next)) {} !y.hasNext - } else false; - } else false; - } + } else false + } else false - def isPubIDChar( c:Char ) = c match { - case '\u0020' | '\u000D' | '\u000A' => true; + def isPubIDChar(c: Char) = c match { + case '\u0020' | '\u000D' | '\u000A' => true case _ if - ('0' < c && c < '9')||('a' < c && c < 'z')||('A' < c && c < 'Z') => true; + ('0' < c && c < '9')||('a' < c && c < 'z')||('A' < c && c < 'Z') => true case '-' | '\''| '(' | ')' | '+' | ',' | '.' | '/' | ':' | '=' | '?' | ';' | '!' | '*' | '#' | '@' | '$' | '_' | '%' => true - case _ => false; + case _ => false } - def checkSysID(s: String): Boolean = { + def checkSysID(s: String): Boolean = s.indexOf('"') == -1 || s.indexOf('\'') == -1 - } - def checkPubID(s: String): Boolean = { - if( s.length() > 0 ) { - val z:Seq[Char] = s; - val y = z.elements; - while( y.hasNext && isPubIDChar( y.next ) ){}; + def checkPubID(s: String): Boolean = + if (s.length() > 0) { + val z:Seq[Char] = s + val y = z.elements + while (y.hasNext && isPubIDChar(y.next)) {} !y.hasNext } else true - } } diff --git a/src/manual/scala/man1/scaladoc.scala b/src/manual/scala/man1/scaladoc.scala index f69209c88c..712e4f31cc 100644 --- a/src/manual/scala/man1/scaladoc.scala +++ b/src/manual/scala/man1/scaladoc.scala @@ -11,10 +11,12 @@ object scaladoc extends Command { protected def cn = new Error().getStackTrace()(0).getClassName() + val scalaLink = Link("Scala 2", "http://scala.epfl.ch/") + val name = Section("NAME", MBold(command) & " " & NDash & " Documentation generator for the " & - Link("Scala 2", "http://scala.epfl.ch/") & " language") + scalaLink & " language") val synopsis = Section("SYNOPSIS", @@ -35,12 +37,26 @@ object scaladoc extends Command { val description = Section("DESCRIPTION", "The " & MBold(command) & " tool reads class and object definitions, " & - "written in the Scala programming language, and generates their API as " & - "HTML files.", + "written in the " & scalaLink & " programming language, and generates " & + "their API as HTML files.", "By default, the generator puts each HTML file in the same directory as " & "its source file. You can specify a separate destination directory with " & - CmdOption("d") & "(see " & Link(Bold("OPTIONS"), "#options") & ", below).") + CmdOption("d") & "(see " & Link(Bold("OPTIONS"), "#options") & ", below).", + + // tags are defined in class "scala.tools.nsc.doc.DocGenerator" + "Supported tag comments are:", + + BulletList( + Mono("@author"), Mono("@deprecated"), + Mono("@exception") & " (two arguments)", + Mono("@param") & " (two arguments)", + Mono("@return"), Mono("@see"), Mono("@since"), + Mono("@throws") & " (two arguments)", + Mono("@todo"), Mono("@version")), + + "See also online document \"" & Link("How to Write Doc Comments for the Javadoc Tool", + "http://java.sun.com/j2se/javadoc/writingdoccomments/") & "\" from Sun.") val options = Section("OPTIONS", @@ -90,9 +106,9 @@ object scaladoc extends Command { def manpage = new Document { title = command - date = "June 8, 2006" + date = "October 4, 2006" author = "Stephane Micheloud" - version = "0.2" + version = "0.3" sections = List( name, synopsis, |