diff options
author | cremet <cremet@epfl.ch> | 2003-11-28 15:42:25 +0000 |
---|---|---|
committer | cremet <cremet@epfl.ch> | 2003-11-28 15:42:25 +0000 |
commit | 21a4dcc99ce03b8663d69a6089f753ce0c360bb8 (patch) | |
tree | 8ba13c0d10a6cde6df31ec1099674a03969b5433 /sources | |
parent | 18be2fe9d82c9a0017d95f9ef7f80c6af2a940fb (diff) | |
download | scala-21a4dcc99ce03b8663d69a6089f753ce0c360bb8.tar.gz scala-21a4dcc99ce03b8663d69a6089f753ce0c360bb8.tar.bz2 scala-21a4dcc99ce03b8663d69a6089f753ce0c360bb8.zip |
- Added the possibility to tell what packages a...
- Added the possibility to tell what packages are to be documented on
the command line. Ex: scaladoc -d api *.scala -- scala java.lang
Diffstat (limited to 'sources')
-rw-r--r-- | sources/scala/tools/scaladoc/HTMLGenerator.java | 86 | ||||
-rw-r--r-- | sources/scala/tools/scaladoc/HTMLGeneratorCommand.java | 6 | ||||
-rw-r--r-- | sources/scala/tools/scaladoc/Location.java | 2 | ||||
-rw-r--r-- | sources/scala/tools/scaladoc/ScalaSearch.java | 124 | ||||
-rw-r--r-- | sources/scala/tools/scaladoc/SymbolTablePrinterFactory.java | 21 |
5 files changed, 170 insertions, 69 deletions
diff --git a/sources/scala/tools/scaladoc/HTMLGenerator.java b/sources/scala/tools/scaladoc/HTMLGenerator.java index 3bff3d34cb..cac689e621 100644 --- a/sources/scala/tools/scaladoc/HTMLGenerator.java +++ b/sources/scala/tools/scaladoc/HTMLGenerator.java @@ -47,6 +47,8 @@ import scalac.util.Debug; import scalac.util.Name; import scalac.util.Names; import scalac.util.Strings; +import SymbolBooleanFunction; +import scalac.util.ScalaProgramArgumentParser; /** * The class <code>HTMLGenerator</code> generates @@ -159,10 +161,6 @@ public class HTMLGenerator { */ protected final Global global; - /** Maps classes to their direct implementing classes or modules. - */ - protected final Map subs; - /** Directory where to put generated HTML pages. */ protected File directory; @@ -222,6 +220,10 @@ public class HTMLGenerator { */ protected final Symbol root; + /** Documented Symbols. + */ + protected SymbolBooleanFunction isDocumented; + /** * Creates a new instance. * @@ -230,7 +232,6 @@ public class HTMLGenerator { protected HTMLGenerator(Global global) { this.global = global; this.root = global.definitions.ROOT; - this.subs = ScalaSearch.subTemplates(root); this.uri = Location.makeURI("."); assert global.args instanceof HTMLGeneratorCommand; @@ -244,6 +245,16 @@ public class HTMLGenerator { this.stylesheet = args.stylesheet.value; this.noindex = args.noindex.value; this.validate = args.validate.value; + Symbol[] packages = getPackages(args.packages); + final DocSyms docSyms = new DocSyms(global, packages); + this.isDocumented = new SymbolBooleanFunction() { + public boolean apply(Symbol sym) { + return docSyms.contains(sym) && ScalaSearch.isRelevant(sym); +// (ScalaSearch.isRelevant(sym) || +// ((sym.isModuleClass() && !sym.isPackage()*/) +// && ScalaSearch.isRelevant(sym.module()))); + } + }; } /** Relative URL of the definition of the given symbol. @@ -252,6 +263,20 @@ public class HTMLGenerator { return page.rel(Location.get(sym)); } + /** Get the list pf packages to be documented. + */ + protected Symbol[] getPackages(ScalaProgramArgumentParser option) { + if (option.main != null) { + Symbol[] packages = new Symbol[option.args.length + 1]; + packages[0] = global.definitions.getClass(Name.fromString(option.main)).module(); + for(int i = 0; i < option.args.length; i++) + packages[i+1] = global.definitions.getClass(Name.fromString(option.args[i])).module(); + return packages; + } + else + return new Symbol[] { root }; + } + /** * Open a new documentation page and make it the current page. * @param uri URL of the page @@ -265,7 +290,7 @@ public class HTMLGenerator { title, representation, stylesheet/*, script*/); // Create a printer to print symbols and types. - symtab = SymbolTablePrinterFactory.makeHTML(page); + symtab = SymbolTablePrinterFactory.makeHTML(page, isDocumented); page.open(); } @@ -314,7 +339,8 @@ public class HTMLGenerator { ScalaSearch.foreach(root, new ScalaSearch.SymFun() { public void apply(Symbol sym) { - if (ScalaSearch.isContainer(sym)) { + if (ScalaSearch.isContainer(sym) && + isDocumented.apply(sym)) { createPages(sym); if (sym.isPackage()) createContainerIndexPage(sym); @@ -362,32 +388,6 @@ public class HTMLGenerator { return comment; } - private Symbol[][] splitMembers(Symbol[] syms) { - List fields = new LinkedList(); - List methods = new LinkedList(); - List objects = new LinkedList(); - List traits = new LinkedList(); - List classes = new LinkedList(); - List packages = new LinkedList(); - for (int i = 0; i < syms.length; i++) { - Symbol sym = syms[i]; - if (sym.isTrait()) traits.add(sym); - else if (sym.isClass()) classes.add(sym); - else if (sym.isPackage()) packages.add(sym); - else if (sym.isModule()) objects.add(sym); - else if (sym.isMethod()) methods.add(sym); - else fields.add(sym); - } - return new Symbol[][] { - (Symbol[]) fields.toArray(new Symbol[fields.size()]), - (Symbol[]) methods.toArray(new Symbol[methods.size()]), - (Symbol[]) objects.toArray(new Symbol[objects.size()]), - (Symbol[]) traits.toArray(new Symbol[traits.size()]), - (Symbol[]) classes.toArray(new Symbol[classes.size()]), - (Symbol[]) packages.toArray(new Symbol[packages.size()]) - }; - } - /** * Generates a HTML page for a class or object definition as well * as pages for every inner class or object. @@ -412,7 +412,7 @@ public class HTMLGenerator { "Trait", "Class", "Package" }; // "Constructor" String[] inherited = new String[]{ "Fields", "Methods", "Objects", "Traits", "Classes", "Packages" }; - Symbol[][] members = splitMembers(ScalaSearch.members(sym)); + Symbol[][] members = ScalaSearch.splitMembers(ScalaSearch.members(sym, isDocumented)); for (int i = 0; i < members.length; i++) { addMemberSummary(members[i], titles[i] + " Summary"); if (i == 1) addInheritedMembers(sym, inherited[i]); @@ -563,6 +563,9 @@ public class HTMLGenerator { printTemplateHtmlSignature(sym, false); // implementing classes or modules + // Maps classes to their direct implementing classes or modules + Map subs = ScalaSearch.subTemplates(root, isDocumented); + if (sym.isClass()) { List subList = (List) subs.get(sym); if (subList != null && subList.size() != 0) { @@ -974,7 +977,7 @@ public class HTMLGenerator { page.printHeader(ATTRS_META, getGenerator()); page.printOpenBody(); - Symbol[] packages = ScalaSearch.getSortedPackageList(root); + Symbol[] packages = ScalaSearch.getSortedPackageList(root, isDocumented); addDocumentationTitle(new XMLAttribute[]{ new XMLAttribute("class", "doctitle-larger")}); @@ -1009,11 +1012,11 @@ public class HTMLGenerator { String[] titles = new String[]{ "Objects", "Traits", "Classes" }; if (sym.isRoot()) { - Symbol[][] members = ScalaSearch.getSubContainerMembers(root); + Symbol[][] members = ScalaSearch.getSubContainerMembers(root, isDocumented); for (int i = 0; i < titles.length; i++) addSymbolTable(members[i], "All " + titles[i], true); } else { - Symbol[][] members = splitMembers(ScalaSearch.members(sym)); + Symbol[][] members = ScalaSearch.splitMembers(ScalaSearch.members(sym, isDocumented)); for (int i = 0; i < titles.length; i++) addSymbolTable(members[i + 2], titles[i], false); } @@ -1048,7 +1051,7 @@ public class HTMLGenerator { page.printlnCTag("table"); page.printlnSTag("br"); - Pair index = ScalaSearch.index(root); + Pair index = ScalaSearch.index(root, isDocumented); Character[] chars = (Character[]) index.fst; Map map = (Map) index.snd; for (int i = 0; i < chars.length; i++) @@ -1187,8 +1190,9 @@ public class HTMLGenerator { * symbol (including itself). */ protected void printPath(Symbol sym, String destinationFrame) { + sym = sym.isModuleClass() ? sym.module() : sym; String name = removeHtmlSuffix(Location.getURI(sym).toString()); - if (ScalaSearch.isDocumented(sym)) { + if (isDocumented.apply(sym)) { String target = definitionURL(sym); page.printlnAhref(target, destinationFrame, name); } @@ -1203,7 +1207,7 @@ public class HTMLGenerator { */ protected void addIndexEntry(Symbol symbol) { // kind - String keyword = symtab.getSymbolKeyword(symbol); + String keyword = symbol.isPackage() ? "package" : symtab.getSymbolKeyword(symbol); if (keyword != null) page.print(keyword).space(); // name symtab.printDefinedSymbolName(symbol, true); @@ -1278,7 +1282,7 @@ public class HTMLGenerator { System.err.println("Warning: Scaladoc: not found: " + tag); return tag.text; } - else if (!ScalaSearch.isDocumented(sym)) { + else if (!isDocumented.apply(sym)) { System.err.println("Warning: Scaladoc: not referenced: " + tag); return tag.text; } diff --git a/sources/scala/tools/scaladoc/HTMLGeneratorCommand.java b/sources/scala/tools/scaladoc/HTMLGeneratorCommand.java index 6319cf0eb6..4b82dd1a78 100644 --- a/sources/scala/tools/scaladoc/HTMLGeneratorCommand.java +++ b/sources/scala/tools/scaladoc/HTMLGeneratorCommand.java @@ -20,6 +20,7 @@ import scalac.util.ClassPath; import scalac.util.OptionParser; import scalac.util.Reporter; import scalac.util.StringOptionParser; +import scalac.util.ScalaProgramArgumentParser; import scalac.util.Strings; /** @@ -42,6 +43,8 @@ public class HTMLGeneratorCommand extends CompilerCommand { public final BooleanOptionParser noindex; public final BooleanOptionParser validate; + public final ScalaProgramArgumentParser packages; + //######################################################################## // Public Constructors @@ -125,6 +128,8 @@ public class HTMLGeneratorCommand extends CompilerCommand { "Add a link at the bottom of each generated page", false); + this.packages = new ScalaProgramArgumentParser(this); + remove(nowarn); remove(verbose); remove(debug); @@ -161,6 +166,7 @@ public class HTMLGeneratorCommand extends CompilerCommand { add(8, doctype); add(9, docencoding); add(10, validate); + add(11, packages); } //######################################################################## diff --git a/sources/scala/tools/scaladoc/Location.java b/sources/scala/tools/scaladoc/Location.java index 35f7e12cd4..ecd9905e02 100644 --- a/sources/scala/tools/scaladoc/Location.java +++ b/sources/scala/tools/scaladoc/Location.java @@ -65,7 +65,7 @@ public class Location { } // where static public String getName(Symbol sym) { - return sym.isClass() ? sym.nameString() + CLASS_SUFFIX : sym.nameString(); + return sym.isClass() ? sym.simpleName().toString() + CLASS_SUFFIX : sym.simpleName().toString(); } // where static private final Map/*<Symbol, Integer>*/ ids = new HashMap(); diff --git a/sources/scala/tools/scaladoc/ScalaSearch.java b/sources/scala/tools/scaladoc/ScalaSearch.java index 23eea17d17..cd279b2181 100644 --- a/sources/scala/tools/scaladoc/ScalaSearch.java +++ b/sources/scala/tools/scaladoc/ScalaSearch.java @@ -15,6 +15,8 @@ import java.util.Iterator; import java.util.LinkedList; import java.util.List; import java.util.Map; +import java.util.Set; +import java.util.HashSet; import ch.epfl.lamp.util.Pair; @@ -70,15 +72,8 @@ public class ScalaSearch { /** Test if the given symbol is relevant for the documentation. */ public static boolean isRelevant(Symbol sym) { - return !isGenerated(sym) && !isLazy(sym) && !isPrivate(sym); - } - - /** Test if the given symbol is a documented member, i.e. if it - * appears in the documentation. - */ - public static boolean isDocumented(Symbol sym) { - return isRelevant(sym) || - (sym.isModuleClass() && isRelevant(sym.module())); + return !isGenerated(sym) && !isLazy(sym) && !isPrivate(sym) && + !(sym.isPackage() && sym.isClass()); } //////////////////////// SCOPE ITERATOR ////////////////////////////// @@ -163,6 +158,35 @@ public class ScalaSearch { return new Symbol[0]; } + /** Apply a given function to all symbols below the given symbol + * in the symbol table. + */ + public static void foreach(Symbol sym, SymFun fun, SymbolBooleanFunction isDocumented) { + if (isDocumented.apply(sym) && isRelevant(sym)) { + fun.apply(sym); + Symbol[] members = members(sym, isDocumented); + for(int i = 0; i < members.length; i++) + foreach(members[i], fun, isDocumented); + } + } + + /** Return all members of a container symbol. + */ + public static Symbol[] members(Symbol sym, SymbolBooleanFunction isDocumented) { + if (isContainer(sym) && !isLazy(sym)) { + List memberList = new LinkedList(); + SymbolIterator i = new UnloadLazyIterator(sym.members().iterator(false)); + while (i.hasNext()) { + Symbol member = i.next(); + if (isDocumented.apply(member) && isRelevant(sym)) + memberList.add(member); + } + return (Symbol[]) memberList.toArray(new Symbol[memberList.size()]); + } + else + return new Symbol[0]; + } + ///////////////////////// COMPARATORS /////////////////////////////// /** @@ -204,7 +228,7 @@ public class ScalaSearch { * * @param root */ - public static Symbol[] getSortedPackageList(Symbol root) { + public static Symbol[] getSortedPackageList(Symbol root, SymbolBooleanFunction isDocumented) { final List packagesAcc = new LinkedList(); foreach(root, new SymFun() { @@ -212,13 +236,13 @@ public class ScalaSearch { if (sym.isPackage()) packagesAcc.add(sym); } - }); + }, isDocumented); Symbol[] packages = (Symbol[]) packagesAcc.toArray(new Symbol[packagesAcc.size()]); Arrays.sort(packages, symPathOrder); return packages; } - public static Symbol[][] getSubContainerMembers(Symbol root) { + public static Symbol[][] getSubContainerMembers(Symbol root, SymbolBooleanFunction isDocumented) { final List objectsAcc = new LinkedList(); final List traitsAcc = new LinkedList(); final List classesAcc = new LinkedList(); @@ -232,7 +256,7 @@ public class ScalaSearch { else if (sym.isModule() && !sym.isPackage()) objectsAcc.add(sym); } - } + }, isDocumented ); Symbol[] objects = (Symbol[]) objectsAcc.toArray(new Symbol[objectsAcc.size()]); Symbol[] traits = (Symbol[]) traitsAcc.toArray(new Symbol[traitsAcc.size()]); @@ -243,6 +267,32 @@ public class ScalaSearch { return new Symbol[][]{ objects, traits, classes }; } + public static Symbol[][] splitMembers(Symbol[] syms) { + List fields = new LinkedList(); + List methods = new LinkedList(); + List objects = new LinkedList(); + List traits = new LinkedList(); + List classes = new LinkedList(); + List packages = new LinkedList(); + for (int i = 0; i < syms.length; i++) { + Symbol sym = syms[i]; + if (sym.isTrait()) traits.add(sym); + else if (sym.isClass()) classes.add(sym); + else if (sym.isPackage()) packages.add(sym); + else if (sym.isModule()) objects.add(sym); + else if (sym.isMethod()) methods.add(sym); + else fields.add(sym); + } + return new Symbol[][] { + (Symbol[]) fields.toArray(new Symbol[fields.size()]), + (Symbol[]) methods.toArray(new Symbol[methods.size()]), + (Symbol[]) objects.toArray(new Symbol[objects.size()]), + (Symbol[]) traits.toArray(new Symbol[traits.size()]), + (Symbol[]) classes.toArray(new Symbol[classes.size()]), + (Symbol[]) packages.toArray(new Symbol[packages.size()]) + }; + } + /////////////////// IMPLEMENTING CLASSES OR OBJECTS ////////////////////// /** @@ -253,7 +303,7 @@ public class ScalaSearch { * * @param root */ - public static Map subTemplates(Symbol root) { + public static Map subTemplates(Symbol root, SymbolBooleanFunction isDocumented) { final Map subs = new HashMap(); foreach(root, new SymFun() { void apply(Symbol sym) { if (sym.isClass() || sym.isModule()) { @@ -269,7 +319,7 @@ public class ScalaSearch { } } } - }); + }, isDocumented); return subs; } @@ -282,7 +332,7 @@ public class ScalaSearch { * * @param root */ - public static Pair index(Symbol root) { + public static Pair index(Symbol root, final SymbolBooleanFunction isDocumented) { final Map index = new HashMap(); // collecting foreach(root, new SymFun() { void apply(Symbol sym) { @@ -298,7 +348,7 @@ public class ScalaSearch { symList.add(sym); } } - }); + }, isDocumented); // sorting Character[] chars = (Character[]) index.keySet() .toArray(new Character[index.keySet().size()]); @@ -391,3 +441,43 @@ public class ScalaSearch { return new Pair(owners, groups); } } + +/** Compute documented symbols. */ +public class DocSyms { + + Set syms; + + DocSyms(Global global, Symbol[] packages) { + syms = new HashSet(); + for(int i = 0; i < packages.length; i++) { + Symbol pack = packages[i]; + // add all sub-members. + ScalaSearch.foreach(pack, + new ScalaSearch.SymFun() { + public void apply(Symbol sym) { + syms.add(sym); + } + } + ); + // add all super packages. + Symbol owner = pack.owner(); + while (owner != Symbol.NONE) { + syms.add(owner.module()); + owner = owner.owner(); + } + } + } + + public boolean contains(Symbol sym) { + boolean res = false; + if (sym.isParameter()) + res = contains(sym.classOwner()); + else + res = (syms.contains(sym) || syms.contains(sym.module())); + return res; + } +} + +public abstract class SymbolBooleanFunction { + public abstract boolean apply(Symbol sym); +} diff --git a/sources/scala/tools/scaladoc/SymbolTablePrinterFactory.java b/sources/scala/tools/scaladoc/SymbolTablePrinterFactory.java index 9ab62ca889..5a5007f593 100644 --- a/sources/scala/tools/scaladoc/SymbolTablePrinterFactory.java +++ b/sources/scala/tools/scaladoc/SymbolTablePrinterFactory.java @@ -22,17 +22,18 @@ import scalac.util.Debug; import scalac.util.Name; import scalac.util.Names; import scalac.util.Strings; +import SymbolBooleanFunction; class SymbolTablePrinterFactory { - public static SymbolTablePrinter makeHTML(final Page page) { + public static SymbolTablePrinter makeHTML(final Page page, final SymbolBooleanFunction isDocumented) { return new SymbolTablePrinter(page.getCodePrinter()) { public void printSymbol(Symbol sym, boolean addLink) { String name = sym.nameString(); if (global.debug) name = sym.name.toString(); - if (ScalaSearch.isDocumented(sym)) + if (isDocumented.apply(sym)) if (addLink) page.printAhref(page.rel(Location.get(sym)), page.destinationFrame, name); @@ -50,7 +51,7 @@ class SymbolTablePrinterFactory { Type result = getTypeToPrintForPrefix0(prefix); if (result == prefix || result == null) { return - cleanPrefix(result, global); + cleanPrefix(result, global, isDocumented); } prefix = result; } @@ -85,7 +86,7 @@ class SymbolTablePrinterFactory { * * @param prefix */ - static protected Type cleanPrefix(Type prefix, Global global) { + static protected Type cleanPrefix(Type prefix, Global global, SymbolBooleanFunction isDocumented) { if (prefix == null) return null; if (prefix.symbol().kind == Kinds.NONE) return null; if (prefix.symbol().isRoot()) return null; @@ -97,25 +98,25 @@ class SymbolTablePrinterFactory { switch(prefix) { case ThisType(Symbol sym): - if (sym.isPackage() && ScalaSearch.isDocumented(sym.module())) + if (sym.isPackage() && isDocumented.apply(sym.module())) return null; - else if (ScalaSearch.isDocumented(sym)) + else if (isDocumented.apply(sym)) return null; else return prefix; case TypeRef(Type pre, Symbol sym, Type[] args): - Type pre1 = cleanPrefix(pre, global); - if (pre1 == null && args.length == 0 && ScalaSearch.isDocumented(sym)) + Type pre1 = cleanPrefix(pre, global, isDocumented); + if (pre1 == null && args.length == 0 && isDocumented.apply(sym)) return null; else { pre1 = pre1 == null ? global.definitions.ROOT.thisType() : pre1; return Type.typeRef(pre1, sym, args); } case SingleType(Type pre, Symbol sym): - Type pre1 = cleanPrefix(pre, global); + Type pre1 = cleanPrefix(pre, global, isDocumented); if (pre1 == null) { if (sym.isClass() || sym.isModule()) - if (ScalaSearch.isDocumented(sym)) { + if (isDocumented.apply(sym)) { return null; } else |