From a708aa88f4b7d03fe272a8bfff8d42c389592964 Mon Sep 17 00:00:00 2001 From: Gilles Dubochet Date: Wed, 2 Jun 2010 16:23:43 +0000 Subject: [scaladoc] Updated man page for Scaladoc 2. --- src/manual/scala/man1/scaladoc.scala | 127 ++++++++++++++++++----------------- 1 file changed, 66 insertions(+), 61 deletions(-) (limited to 'src/manual') diff --git a/src/manual/scala/man1/scaladoc.scala b/src/manual/scala/man1/scaladoc.scala index 77a2b88ce7..ba4f2ff0e2 100644 --- a/src/manual/scala/man1/scaladoc.scala +++ b/src/manual/scala/man1/scaladoc.scala @@ -1,6 +1,7 @@ /* NSC -- new Scala compiler - * Copyright 2005-2010 LAMP/EPFL + * Copyright LAMP/EPFL * @author Stephane Micheloud + * @author Gilles Dubochet */ package scala.man1 @@ -44,82 +45,89 @@ object scaladoc extends Command { 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("@pre"), - 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.") + "The recognised format of comments in source is described in the " & Link("online documentation", + "http://lampsvn.epfl.ch/trac/scala/wiki/Scaladoc")) val options = Section("OPTIONS", - "The generator has a set of standard options that are supported on the " & - "current development environment and will be supported in future releases.", - - Section("Standard Options", + Section("Documentation Options", DefinitionList( Definition( CmdOption("d", Argument("directory")), - "Specify where to place generated class files."), + "Specify where to generate documentation."), Definition( - CmdOption("access:"), - "Show only public, protected/public (default) or all classes " & - "and members (" & Mono("public") & ",protected,private)"), + CmdOption("doc-title", Argument("title")), + "Define the overall title of the documentation, typically the name of the library being documented."), Definition( - CmdOption("windowtitle", Argument("windowtitle")), - "Specify window title of generated HTML documentation"), + CmdOption("doc-version", Argument("version")), + "Define the overall version number of the documentation, typically the version of the library being documented."), Definition( - CmdOption("doctitle", Argument("doctitle")), - "Include title for the overview page"), + CmdOption("doc-source-url", Argument("url")), + "Define a URL to be concatenated with source locations for link to source files."), Definition( - CmdOption("stylesheetfile", Argument("stylesheetfile")), - "File to change style of the generated documentation"), + CmdOption("version"), + "Print product version and exit."), Definition( - CmdOption("header", Argument("pageheader")), - "Include header text for each page"), + /*CmdOption("?") & "| " &*/ CmdOption("help"), + "Print a synopsis of standard options."))), + + Section("Compier Options", + DefinitionList( Definition( - CmdOption("footer", Argument("pagefooter")), - "Include footer text for each page"), + CmdOption("verbose"), + "Output messages about what the compiler is doing"), Definition( - CmdOption("top", Argument("pagetop")), - "Include top text for each page"), + CmdOption("deprecation"), + SeqPara( + "Indicate whether source should be compiled with deprecation " & + "information; defaults to " & Mono("off") & " (" & + "accepted values are: " & Mono("on") & ", " & Mono("off") & + ", " & Mono("yes") & " and " & Mono("no") & ")", + "Available since Scala version 2.2.1")), Definition( - CmdOption("bottom", Argument("pagebottom")), - "Include bottom text for each page"), + CmdOption("classpath", Argument("path")), + SeqPara( + "Specify where to find user class files (on Unix-based systems " & + "a colon-separated list of paths, on Windows-based systems, a " & + "semicolon-separate list of paths). This does not override the " & + "built-in (" & Mono("\"boot\"") & ") search path.", + "The default class path is the current directory. Setting the " & + Mono("CLASSPATH") & " variable or using the " & Mono("-classpath") & " " & + "command-line option overrides that default, so if you want to " & + "include the current directory in the search path, you must " & + "include " & Mono("\".\"") & " in the new settings.")), Definition( - CmdOption("version"), - "Print product version and exit."), + CmdOption("sourcepath", Argument("path")), + "Specify where to find input source files."), Definition( - /*CmdOption("?") & "| " &*/ CmdOption("help"), - "Print a synopsis of standard options.")))) - - val examples = Section("EXAMPLES", - - DefinitionList( - Definition( - "Generate documentation for a Scala program", - CmdLine("HelloWorld.scala")), - Definition( - "Generation documentation for a Scala program to the destination " & - "directory " & Bold("classes"), - CmdLine(CmdOption("d", "api") & "HelloWorld.scala")), - Definition( - "Generate documentation for all Scala files found in the source " & - "directory " & Bold("src") & " to the destination directory " & - Bold("api"), - CmdLine(CmdOption("d", "api") & "src/*.scala")))) + CmdOption("bootclasspath", Argument("path")), + "Override location of bootstrap class files (where to find the " & + "standard built-in classes, such as \"" & Mono("scala.List") & "\")."), + Definition( + CmdOption("extdirs", Argument("dirs")), + "Override location of installed extensions."), + Definition( + CmdOption("encoding", Argument("encoding")), + SeqPara( + "Specify character encoding used by source files.", + "The default value is platform-specific (Linux: " & Mono("\"UTF8\"") & + ", Windows: " & Mono("\"Cp1252\"") & "). Executing the following " & + "code in the Scala interpreter will return the default value " & + "on your system:", + MBold(" scala> ") & + Mono("new java.io.InputStreamReader(System.in).getEncoding")))))) val exitStatus = Section("EXIT STATUS", MBold(command) & " returns a zero exist status if it succeeds to process " & "the specified input files. Non zero is returned in case of failure.") + override val authors = Section("AUTHORS", + + "This version of Scaladoc was written by Gilles Dubochet with contributions by Pedro Furlanetto and Johannes Rudolph. " & + "It is based on the original Scaladoc (Sean McDirmid, Geoffrey Washburn, Vincent Cremet and Stéphane Michleoud), " & + "on vScaladoc (David Bernard), as well as on an unreleased version of Scaladoc 2 (Manohar Jonnalagedda).") + val seeAlso = Section("SEE ALSO", Link(Bold("fsc") & "(1)", "fsc.html") & ", " & @@ -130,20 +138,17 @@ object scaladoc extends Command { def manpage = new Document { title = command - date = "May 1, 2007" - author = "Stephane Micheloud" - version = "0.4" + date = "2 June 2010" + author = "Gilles Dubochet" + version = "2.0" sections = List( name, synopsis, parameters, description, options, - examples, exitStatus, authors, - bugs, - copyright, seeAlso) } } -- cgit v1.2.3