From beb9d190d93d538a781db9d835b86d11ceb26158 Mon Sep 17 00:00:00 2001 From: "Lukas B." Date: Sat, 7 Dec 2013 21:51:24 +0100 Subject: [PATCH 01/21] Remove closing brace in HTMLToTex which caused errors with ordered list tags --- src/org/wonderly/doclets/HTMLToTex.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/org/wonderly/doclets/HTMLToTex.java b/src/org/wonderly/doclets/HTMLToTex.java index de20257..07d93eb 100644 --- a/src/org/wonderly/doclets/HTMLToTex.java +++ b/src/org/wonderly/doclets/HTMLToTex.java @@ -360,7 +360,7 @@ else if (refname != null) } else if (match("")) { ret.append("\n\\end{itemize}\n"); } else if (match("")) { - ret.append("}\n\\end{enumerate}"); + ret.append("\n\\end{enumerate}"); } else if (startsWith(" Date: Mon, 9 Dec 2013 20:23:09 +0100 Subject: [PATCH 02/21] Update Eclipse project to use open jdk 7's tools.jar --- .classpath | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.classpath b/.classpath index e034f20..cc36a5e 100644 --- a/.classpath +++ b/.classpath @@ -2,6 +2,6 @@ - + From 95ad42f0798b234c433b7ac5bb611255386173fa Mon Sep 17 00:00:00 2001 From: Lukas Boehm Date: Mon, 9 Dec 2013 20:23:55 +0100 Subject: [PATCH 03/21] Quick hack to exclude classes with '@excludeFromTex' tag --- src/org/wonderly/doclets/TexDoclet.java | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/org/wonderly/doclets/TexDoclet.java b/src/org/wonderly/doclets/TexDoclet.java index b12acfd..9653a3f 100644 --- a/src/org/wonderly/doclets/TexDoclet.java +++ b/src/org/wonderly/doclets/TexDoclet.java @@ -231,6 +231,10 @@ public int compare(ClassDoc o1, ClassDoc o2) { } private static void printClass(ClassDoc cd) { + if (cd.tags("@excludeFromTex").length > 0) { + return; + } + String type; if (cd.isInterface()) { type = "interface"; From c1fc4d0ebfb5ee1977f876e8d38d0f632b52a4c6 Mon Sep 17 00:00:00 2001 From: Lukas Boehm Date: Mon, 9 Dec 2013 20:31:33 +0100 Subject: [PATCH 04/21] Replace preamble.tex with '\input'able docletcommands.tex (thanks to @vincent23) --- preamble.tex => docletcommands.tex | 82 ++++++++++-------------------- 1 file changed, 26 insertions(+), 56 deletions(-) rename preamble.tex => docletcommands.tex (71%) diff --git a/preamble.tex b/docletcommands.tex similarity index 71% rename from preamble.tex rename to docletcommands.tex index 01cda32..35b54ef 100644 --- a/preamble.tex +++ b/docletcommands.tex @@ -1,23 +1,3 @@ -% This is an example preamble for texdoclet generated output. -% Used like this it produces a standalone document. However it should be easy -% to copy these definitions into your own document and use \input{docs.tex} -% where you want your texdoc documentation. - -% The following is an example to put packagename and class into the page -% headings. -\documentclass[a4paper,11pt,parskip=half]{scrbook} - -% Make sure you use at least the following packages -\usepackage{color} -% The texdoclet output is in UTF-8. I strongly recommend writing the latex -% source in UTF-8 encoding anyway... -\usepackage[utf8]{inputenc} -\usepackage[T1]{fontenc} -\usepackage{lmodern} - -% The following packages are not striclty necessary to get texdoclet working -\usepackage{hyperref} - \pagestyle{myheadings} % Initially we're not in a package or class \def\packagename{} @@ -36,64 +16,65 @@ } % Environment for packages \newenvironment{texdocpackage}[1]{% - \newpage{}\gdef\packagename{#1}\chapter{Package \texttt{#1}} - \rule{\hsize}{.7mm} + \newpage{}\gdef\packagename{#1}\chapter{Package \texttt{#1}} + \rule{\hsize}{.7mm} }{} % Environment for classes, interfaces % Argument 1: "class" or "interface" % Argument 2: the name of the class/interface \newenvironment{texdocclass}[2]{% - \gdef\classname{#2} - \section{\texttt{#1 \textbf{#2}}} -}{\newpage{}} + \gdef\classname{#2} + \section{\texttt{#1 \textbf{#2}}} +% }{\newpage{}} +}{} % removed \newpage % Environment for class description \newenvironment{texdocclassintro}{ - \subsection*{Description} + \subsection*{Description} }{ } % Environment around class fields \newenvironment{texdocclassfields}{% - \subsection*{Attributes} - \begin{itemize} + \subsection*{Attributes} + \begin{itemize} }{% - \end{itemize} + \end{itemize} } % Environment around class methods \newenvironment{texdocclassmethods}{% - \subsection*{Methods} - \begin{itemize} + \subsection*{Methods} + \begin{itemize} }{% - \end{itemize} + \end{itemize} } % Environment around class Constructors \newenvironment{texdocclassconstructors}{% - \subsection*{Constructors} - \begin{itemize} + \subsection*{Constructors} + \begin{itemize} }{% - \end{itemize} + \end{itemize} } % Environment around enum constants \newenvironment{texdocenums}{% - \subsection*{Enum Constants} - \begin{itemize} + \subsection*{Enum Constants} + \begin{itemize} }{% - \end{itemize} + \end{itemize} } % Environment around "See also"-Blocks (\texdocsee invocations) % Argument 1: Text preceding the references \newenvironment{texdocsees}[1]{ - - \textbf{#1:} - \begin{itemize} + + \textbf{#1:} + \begin{itemize} }{% - \end{itemize} + \end{itemize} } % Formats a single field % Argument 1: modifiers @@ -136,10 +117,10 @@ % Environment around \texdocparameter invocations \newenvironment{texdocparameters}{% - \minisec{Parameters} - \begin{tabular}{ll} + \minisec{Parameters} + \begin{tabular}{ll} }{% - \end{tabular} + \end{tabular} } % Environment around \texdocthrow invocations @@ -176,14 +157,3 @@ \relax\else {$($ in \ref{#1}, page \pageref{#1}$)$} \fi} - -% --------------------------------------------------------------------------- -% TexDoc macros end -% --------------------------------------------------------------------------- - -\begin{document} - - \tableofcontents - \input{docs.tex} - -\end{document} From 04b10d112f5e03ebd4dfebebcc0d0a9e322fc0ca Mon Sep 17 00:00:00 2001 From: "Lukas B." Date: Mon, 9 Dec 2013 20:39:03 +0100 Subject: [PATCH 05/21] Add build instructions and change the credits --- README.markdown | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/README.markdown b/README.markdown index 086a1e8..33bedc9 100644 --- a/README.markdown +++ b/README.markdown @@ -3,9 +3,21 @@ TexDoclet This is a javadoc doclet - a plugin for the [javadoc tool](http://java.sun.com/j2se/javadoc/). This doclet produces output suitable to be included into LaTeX documents. -This version is based on [TexDoclet](https://texdoclet.dev.java.net/) from Gregg Wonderly. -A lot of the code was rewritten and changed to support a separation from content -and layout. The sourcecode is also cleaner than the original. +This version is based on [TexDoclet](https://texdoclet.dev.java.net/) from Gregg Wonderly with the changes made and +applied to by [Matthias Braun](https://github.com/MatzeB). See his github project for details. + +My fork adapts the doclet to meet the requirements of our project [lambda-alligatoren](https://github.com/vincent23/lambda-alligatoren). +In detail, those are: +* @excludeFromTex tag support +* modify the original "preamble.tex" to become an "\\input"-able "docletcommands.tex" (thanks to [@vincent23](https://github.com/vincent23)) +* fix a surplus "}" in HTMLtoTex which broke ordered lists + +Build instructions +------------------ +* The ant Build.xml file provided does NOT run on its own. +* You will need to open the project in Eclipse +* You will probably have to update the path to "tools.jar" in the project's build path properties if you aren't on linux and/or using an SDK different to openjdk 7 +* You can build a self-contained doclet jar file by exporting the project as jar from eclipse Features -------- @@ -33,7 +45,7 @@ Usage Use \input{docs.tex} inside your document to include the generated documentation. -Author/Contact +Original Author/Contact -------------- Matthias Braun From f436be7e9a642a6fae7701031752a8780b8d34b9 Mon Sep 17 00:00:00 2001 From: Lukas Boehm Date: Tue, 10 Dec 2013 22:24:33 +0100 Subject: [PATCH 06/21] Push all chapter/section declarations one level down (section->subsection...) since chapter is not available in smaller documents and I personally don't like to use \parts if I want to have more than just the JavaDoc section in my document --- docletcommands.tex | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docletcommands.tex b/docletcommands.tex index 35b54ef..257ba72 100644 --- a/docletcommands.tex +++ b/docletcommands.tex @@ -16,7 +16,7 @@ } % Environment for packages \newenvironment{texdocpackage}[1]{% - \newpage{}\gdef\packagename{#1}\chapter{Package \texttt{#1}} + \newpage{}\gdef\packagename{#1}\section{Package \texttt{#1}} \rule{\hsize}{.7mm} }{} @@ -25,19 +25,19 @@ % Argument 2: the name of the class/interface \newenvironment{texdocclass}[2]{% \gdef\classname{#2} - \section{\texttt{#1 \textbf{#2}}} + \subsection{\texttt{#1 \textbf{#2}}} % }{\newpage{}} }{} % removed \newpage % Environment for class description \newenvironment{texdocclassintro}{ - \subsection*{Description} + \subsubsection*{Description} }{ } % Environment around class fields \newenvironment{texdocclassfields}{% - \subsection*{Attributes} + \subsubsection*{Attributes} \begin{itemize} }{% \end{itemize} @@ -45,7 +45,7 @@ % Environment around class methods \newenvironment{texdocclassmethods}{% - \subsection*{Methods} + \subsubsection*{Methods} \begin{itemize} }{% \end{itemize} @@ -53,7 +53,7 @@ % Environment around class Constructors \newenvironment{texdocclassconstructors}{% - \subsection*{Constructors} + \subsubsection*{Constructors} \begin{itemize} }{% \end{itemize} @@ -61,7 +61,7 @@ % Environment around enum constants \newenvironment{texdocenums}{% - \subsection*{Enum Constants} + \subsubsection*{Enum Constants} \begin{itemize} }{% \end{itemize} From 5c878f57206edba3548bd66db01689cfefa2d3be Mon Sep 17 00:00:00 2001 From: Lukas Boehm Date: Mon, 16 Dec 2013 18:45:40 +0100 Subject: [PATCH 07/21] Change clearing page not BEFORE but AFTER package --- docletcommands.tex | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docletcommands.tex b/docletcommands.tex index 257ba72..35b9664 100644 --- a/docletcommands.tex +++ b/docletcommands.tex @@ -16,9 +16,9 @@ } % Environment for packages \newenvironment{texdocpackage}[1]{% - \newpage{}\gdef\packagename{#1}\section{Package \texttt{#1}} + \gdef\packagename{#1}\section{Package \texttt{#1}} \rule{\hsize}{.7mm} -}{} +}{\newpage{}} % Environment for classes, interfaces % Argument 1: "class" or "interface" From fbdced4cd526afceb8638c731d4cec1f5a43b4cc Mon Sep 17 00:00:00 2001 From: Lukas Boehm Date: Thu, 19 Dec 2013 22:28:16 +0100 Subject: [PATCH 08/21] Add eclipse local .settings folderto gitignore --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index c0f3701..d84582c 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,3 @@ bin release +.settings From 2a3e67aae1a59a311b09ecaf49162049f616297d Mon Sep 17 00:00:00 2001 From: Lukas Boehm Date: Thu, 19 Dec 2013 22:31:11 +0100 Subject: [PATCH 09/21] Add -silent option. Add implements and extends being shown. --- docletcommands.tex | 20 ++++- src/org/wonderly/doclets/TexDoclet.java | 113 +++++++++++++++++------- 2 files changed, 95 insertions(+), 38 deletions(-) diff --git a/docletcommands.tex b/docletcommands.tex index 35b9664..b36e537 100644 --- a/docletcommands.tex +++ b/docletcommands.tex @@ -1,3 +1,5 @@ +%\usepackage{xparse} + \pagestyle{myheadings} % Initially we're not in a package or class \def\packagename{} @@ -23,11 +25,21 @@ % Environment for classes, interfaces % Argument 1: "class" or "interface" % Argument 2: the name of the class/interface -\newenvironment{texdocclass}[2]{% - \gdef\classname{#2} - \subsection{\texttt{#1 \textbf{#2}}} +% Argument 3 [opt.]: the name of the superclass +% Argument 4 [opt.]: the name of the realized interfaces +% TODO: Probably easier implementation with xparse instead of pgfkeys. Would make substitution ; <-> , unnecessary +\NewDocumentEnvironment{texdocclass}{ m m o o }{% + \gdef\classname{#2} + \subsection[#2]{\texttt{#1 \textbf{#2} + \IfNoValueTF{#3} + {} + {extends #3} + \IfNoValueTF{#4} + {} + {implements #4} + }} % }{\newpage{}} -}{} % removed \newpage +}{}% removed \newpage % Environment for class description \newenvironment{texdocclassintro}{ diff --git a/src/org/wonderly/doclets/TexDoclet.java b/src/org/wonderly/doclets/TexDoclet.java index 9653a3f..3932b78 100644 --- a/src/org/wonderly/doclets/TexDoclet.java +++ b/src/org/wonderly/doclets/TexDoclet.java @@ -29,6 +29,7 @@ /** * Note: This version is heavily modified by Matthias Braun + * Note: This version is even heavier modified by Lukas Böhm * * This class provides a Java 2, javadoc Doclet which generates a * LaTeX2e document out of the java classes that it is used on. @@ -40,6 +41,7 @@ * * @author Gregg Wonderly * @author Matthias Braun + * @author Lukas Böhm */ public class TexDoclet extends Doclet { /** Writer for writing to output file */ @@ -47,6 +49,7 @@ public class TexDoclet extends Doclet { private static String outfile = "docs.tex"; private static String refInlineName = "see "; private static String refBlockName = "See also"; + private static boolean silent = false; /** * Returns how many arguments would be consumed if option is a @@ -56,28 +59,29 @@ public class TexDoclet extends Doclet { * the option to check */ public static int optionLength(String option) { - if (option.equals("-output")) + if (option.equals("-output") + || option.equals("-classfilter") + || option.equals("-see")) { return 2; - else if (option.equals("-classfilter")) - return 2; - else if (option.equals("-see")) - return 2; - else if (option.equals("-help")) { - System.err.println("TexDoclet Usage:"); - System.err.println("-output Specifies the output file to write to. If none"); - System.err.println(" specified, the default is docs.tex in the current"); - System.err.println(" directory."); - System.err.println("-see Specifies the text to use for references created from inline tags."); - System.err.println(" For german javadocs use \"siehe \" for example."); - System.err.println(" The default is \"see \"."); - System.err.println("-See Specifies the text to use for references created from block tags."); - System.err.println(" For german javadocs use \"Siehe auch\" for example."); - System.err.println(" The default is \"See also\"."); - + } + if (option.equals("-help")) { + System.out.println("TexDoclet Usage:"); + System.out.println("-output Specifies the output file to write to. If none"); + System.out.println(" specified, the default is docs.tex in the current"); + System.out.println(" directory."); + System.out.println("-see Specifies the text to use for references created from inline tags."); + System.out.println(" For german javadocs use \"siehe \" for example."); + System.out.println(" The default is \"see \"."); + System.out.println("-See Specifies the text to use for references created from block tags."); + System.out.println(" For german javadocs use \"Siehe auch\" for example."); + System.out.println(" The default is \"See also\"."); + System.out.println("-silent Have the doclet run in silent mode, i.e. all output will be suppressed"); return 1; } - - System.out.println("unknown option " + option); + if (option.equals("-silent")) { + return 1; + } + System.err.println("unknown option: " + option); return Doclet.optionLength(option); } @@ -93,16 +97,28 @@ static public boolean validOptions(String[][] args, DocErrorReporter err) { for (int i = 0; i < args.length; ++i) { if (args[i][0].equals("-output")) { outfile = args[i][1]; - } else if (args[i][0].equals("-see")) { + continue; + } + if (args[i][0].equals("-see")) { refInlineName = args[i][1]; - } else if (args[i][0].equals("-See")) { + continue; + } + if (args[i][0].equals("-See")) { refBlockName = args[i][1]; + continue; } + if (args[i][0].equals("-silent")) { + silent = true; + continue; + } + return false; } return true; } - /** indicate that we can handle (most) 1.5 language features */ + /** + * indicate that we can handle (most) Java 1.5 language features + */ static public LanguageVersion languageVersion() { return LanguageVersion.JAVA_1_5; } @@ -114,9 +130,9 @@ static public LanguageVersion languageVersion() { * the root of the starting document */ public static boolean start(RootDoc root) { - System.out.println("TexDoclet 4.0, Copyright 2009 - Matthias Braun"); - System.out.println("based on TexDoclet v3.0, Copyright 2003 - Gregg Wonderly."); - System.out.println("http://texdoclet.dev.java.net - on the World Wide Web."); + println("TexDoclet 4.0, Copyright 2009 - Matthias Braun"); + println("based on TexDoclet v3.0, Copyright 2003 - Gregg Wonderly."); + println("http://texdoclet.dev.java.net - on the World Wide Web."); try { /* Open output file and force an UTF-8 encoding */ @@ -132,7 +148,7 @@ public static boolean start(RootDoc root) { for (PackageDoc pkg : packages) { - System.out.println("* Package: " + pkg.name()); + println("* Package: " + pkg.name()); os.println("\\begin{texdocpackage}{" + HTMLToTex.convert(pkg.name()) + "}"); os.println("\\label{texdoclet:" + pkg.name() + "}"); @@ -166,10 +182,6 @@ private static void printComment(Tag t) { printComment(t.inlineTags(), null); } - private static void printComment(Tag t, MethodDoc md) { - printComment(t.inlineTags(), md); - } - private static void printComment(Tag[] tags, MethodDoc md) { for (Tag t : tags) { if (t instanceof SeeTag) { @@ -231,7 +243,7 @@ public int compare(ClassDoc o1, ClassDoc o2) { } private static void printClass(ClassDoc cd) { - if (cd.tags("@excludeFromTex").length > 0) { + if (cd.tags("@texignore").length > 0) { return; } @@ -243,10 +255,37 @@ private static void printClass(ClassDoc cd) { } else { type = "class"; } + + String generalization = ""; + Type s = cd.superclassType(); + if (s != null + && !s.toString().equals("java.lang.Object") + && !cd.isEnum() + ) { + generalization = s.toString(); + } + + String realizations = ""; + Type[] itypes = cd.interfaceTypes(); + if (itypes.length > 0) { + realizations += itypes[0].asClassDoc().toString(); + for (int i = 1; i < itypes.length; i++) { + ClassDoc ic = itypes[i].asClassDoc(); + realizations += ic.toString() + ", "; + } + } - os.println("\\begin{texdocclass}{" + type + "}{" - + HTMLToTex.convert(cd.name()) + "}"); - + String classLine = "\\begin{texdocclass}" + + "{" + type + "}" + + "{" + HTMLToTex.convert(cd.name()) + "}"; + if (!generalization.equals("")) { + classLine += "[" + HTMLToTex.convert(generalization) + "]"; + } + if (!realizations.equals("")) { + classLine += "[" + HTMLToTex.convert(realizations) + "]"; + } + os.println(classLine); + os.println("\\label{texdoclet:" + cd.containingPackage().name() + "." + cd.name() + "}"); os.println("\\begin{texdocclassintro}"); printComment(cd); @@ -481,4 +520,10 @@ private static String typeToString(Type type) { } return tstring; } + + private static void println(String s) { + if (!silent) { + System.out.println(s); + } + } } From 7f7c7f958fcfa65b4981e5929066abecdff1317f Mon Sep 17 00:00:00 2001 From: Lukas Boehm Date: Thu, 19 Dec 2013 22:39:53 +0100 Subject: [PATCH 10/21] Update README with info about new features --- README.markdown | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/README.markdown b/README.markdown index 33bedc9..bc020eb 100644 --- a/README.markdown +++ b/README.markdown @@ -26,6 +26,17 @@ Features * Layout is defined by a set of macros outside the tool. This allows you to easily adapt to your own style/document without the need to touch the tools output. +* Classes not intended to be part of the generated tex document can be excluded with a dedicated "texignore" tag. +* Shows generalization and realizations +* Has doclet specific tex commands outsourced to allow easy integration into existing documents. + +Commandline Options +------------------- +* -output: Defines the output file path. Default is "docs.tex" +* -silent: If this option is specified, all usually unnecessary messages are muted. Error messages will be printed still. +* -see: Specifies the text to use for references created from inline tags. The default text is "see " +* -See: Specifies the text to use for references created from block tags. The default text is "See also ". +* -help: Prints a help text similar to this Usage ----- From 09a2f0b5a0d67afec5219fac0ada90c75b04ede0 Mon Sep 17 00:00:00 2001 From: "Lukas B." Date: Fri, 20 Dec 2013 11:00:37 +0100 Subject: [PATCH 11/21] Fix reference from "excludeFromTex" to "texexclude" --- README.markdown | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.markdown b/README.markdown index bc020eb..abf607f 100644 --- a/README.markdown +++ b/README.markdown @@ -8,7 +8,7 @@ applied to by [Matthias Braun](https://github.com/MatzeB). See his github projec My fork adapts the doclet to meet the requirements of our project [lambda-alligatoren](https://github.com/vincent23/lambda-alligatoren). In detail, those are: -* @excludeFromTex tag support +* @texexclude tag support * modify the original "preamble.tex" to become an "\\input"-able "docletcommands.tex" (thanks to [@vincent23](https://github.com/vincent23)) * fix a surplus "}" in HTMLtoTex which broke ordered lists From c649a64c0288875e024241bcf3a716708746db1a Mon Sep 17 00:00:00 2001 From: Lukas Boehm Date: Fri, 20 Dec 2013 20:18:28 +0100 Subject: [PATCH 12/21] Fix warnings and implements/extends being mixed up. Fix doclet doing nothing --- docletcommands.tex | 8 +++++- src/org/wonderly/doclets/HTMLToTex.java | 7 ----- src/org/wonderly/doclets/TexDoclet.java | 35 +++++++++++++------------ 3 files changed, 25 insertions(+), 25 deletions(-) diff --git a/docletcommands.tex b/docletcommands.tex index b36e537..094fc34 100644 --- a/docletcommands.tex +++ b/docletcommands.tex @@ -33,7 +33,13 @@ \subsection[#2]{\texttt{#1 \textbf{#2} \IfNoValueTF{#3} {} - {extends #3} + {% "extends" argument was given + % test, if the argument was empty or not + \ifx&% + \else + extends #3 + \fi + } \IfNoValueTF{#4} {} {implements #4} diff --git a/src/org/wonderly/doclets/HTMLToTex.java b/src/org/wonderly/doclets/HTMLToTex.java index 07d93eb..db19179 100644 --- a/src/org/wonderly/doclets/HTMLToTex.java +++ b/src/org/wonderly/doclets/HTMLToTex.java @@ -6,7 +6,6 @@ import java.util.Properties; import java.util.Stack; -import com.sun.javadoc.ClassDoc; import com.sun.javadoc.MethodDoc; /** @@ -58,12 +57,9 @@ private HTMLToTex() { private String str; private int pos; private StringBuffer ret; - private String block = ""; private String refurl = ""; private String refimg = ""; - private boolean collectBlock; private int chapt = 0; - private int textdepth = 0; private int verbat = 0; private Stack tblstk = new Stack(); private Hashtable colors = new Hashtable(10); @@ -166,7 +162,6 @@ private String convertToTex(String input, MethodDoc md) { this.str = input; ret = new StringBuffer(); - ++textdepth; for (pos = 0; pos < str.length(); ++pos) { char c = str.charAt(pos); switch (c) { @@ -505,8 +500,6 @@ else if (refname != null) break; } } - --textdepth; - /* leave all contexts */ leave(""); diff --git a/src/org/wonderly/doclets/TexDoclet.java b/src/org/wonderly/doclets/TexDoclet.java index 3932b78..bb15486 100644 --- a/src/org/wonderly/doclets/TexDoclet.java +++ b/src/org/wonderly/doclets/TexDoclet.java @@ -50,6 +50,7 @@ public class TexDoclet extends Doclet { private static String refInlineName = "see "; private static String refBlockName = "See also"; private static boolean silent = false; + private static String excludeTag = "@texignore"; /** * Returns how many arguments would be consumed if option is a @@ -75,7 +76,7 @@ public static int optionLength(String option) { System.out.println("-See Specifies the text to use for references created from block tags."); System.out.println(" For german javadocs use \"Siehe auch\" for example."); System.out.println(" The default is \"See also\"."); - System.out.println("-silent Have the doclet run in silent mode, i.e. all output will be suppressed"); + System.out.println("-silent Have the doclet run in silent mode, i.e. all output will be suppressed, except warnings"); return 1; } if (option.equals("-silent")) { @@ -87,6 +88,7 @@ public static int optionLength(String option) { /** * Checks the passed options and their arguments for validity. + * Used to already configure the doclet according to the options passed. * * @param args * the arguments to check @@ -111,7 +113,6 @@ static public boolean validOptions(String[][] args, DocErrorReporter err) { silent = true; continue; } - return false; } return true; } @@ -243,10 +244,11 @@ public int compare(ClassDoc o1, ClassDoc o2) { } private static void printClass(ClassDoc cd) { - if (cd.tags("@texignore").length > 0) { + if (cd.tags(excludeTag).length > 0) { return; } + // Determine type: class or interface String type; if (cd.isInterface()) { type = "interface"; @@ -256,34 +258,33 @@ private static void printClass(ClassDoc cd) { type = "class"; } - String generalization = ""; + // This string will hold the class' section heading + String classLine = "\\begin{texdocclass}" + + "{" + type + "}" + + "{" + HTMLToTex.convert(cd.name()) + "}"; + Type s = cd.superclassType(); if (s != null && !s.toString().equals("java.lang.Object") && !cd.isEnum() ) { - generalization = s.toString(); + String generalization = s.toString(); + classLine += "[" + HTMLToTex.convert(generalization) + "]"; + } else if (!cd.isInterface()) { + // HACKY: if cd is an interface, omit the empty brackets for the "extends" field, for it is used for extended interfaces + classLine += "[]"; } - String realizations = ""; Type[] itypes = cd.interfaceTypes(); if (itypes.length > 0) { - realizations += itypes[0].asClassDoc().toString(); + String realizations = itypes[0].asClassDoc().toString(); for (int i = 1; i < itypes.length; i++) { ClassDoc ic = itypes[i].asClassDoc(); - realizations += ic.toString() + ", "; + realizations += ", " + ic.toString(); } - } - - String classLine = "\\begin{texdocclass}" - + "{" + type + "}" - + "{" + HTMLToTex.convert(cd.name()) + "}"; - if (!generalization.equals("")) { - classLine += "[" + HTMLToTex.convert(generalization) + "]"; - } - if (!realizations.equals("")) { classLine += "[" + HTMLToTex.convert(realizations) + "]"; } + os.println(classLine); os.println("\\label{texdoclet:" + cd.containingPackage().name() + "." + cd.name() + "}"); From 80bbcb52505d9b8ff5906b64b04fc4573f8198a7 Mon Sep 17 00:00:00 2001 From: Lukas Boehm Date: Sat, 21 Dec 2013 20:41:12 +0100 Subject: [PATCH 13/21] Add escaping of double quotes (") --- src/org/wonderly/doclets/HTMLToTex.java | 3 +++ 1 file changed, 3 insertions(+) diff --git a/src/org/wonderly/doclets/HTMLToTex.java b/src/org/wonderly/doclets/HTMLToTex.java index db19179..a243315 100644 --- a/src/org/wonderly/doclets/HTMLToTex.java +++ b/src/org/wonderly/doclets/HTMLToTex.java @@ -172,6 +172,9 @@ private String convertToTex(String input, MethodDoc md) { ret.append(' '); } break; + case '"': + ret.append("\"'"); + break; case '_': case '%': case '$': From 715affdaf2f0f8aaeea04209db559bdf9d3ac7be Mon Sep 17 00:00:00 2001 From: Lukas Boehm Date: Sat, 21 Dec 2013 20:41:44 +0100 Subject: [PATCH 14/21] Fix classnames not being wrapped properly when using @inheritDoc --- docletcommands.tex | 3 +-- src/org/wonderly/doclets/TexDoclet.java | 2 +- 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/docletcommands.tex b/docletcommands.tex index 094fc34..2f4084c 100644 --- a/docletcommands.tex +++ b/docletcommands.tex @@ -1,6 +1,5 @@ %\usepackage{xparse} -\pagestyle{myheadings} % Initially we're not in a package or class \def\packagename{} \def\classname{} @@ -126,7 +125,7 @@ % Inserted when @inheritdoc is used % Argument 1: Class where the documentation was inherited from % Argument 2: Documentation -\newcommand{\texdocinheritdoc}[2]{#2 (\textit{documentation inherited from \texttt{#1})}} +\newcommand{\texdocinheritdoc}[2]{#2 \\(\textit{documentation inherited from \texttt{#1})}} % Formats a single see-BlockTag % Argument 1: text diff --git a/src/org/wonderly/doclets/TexDoclet.java b/src/org/wonderly/doclets/TexDoclet.java index bb15486..a3b2efb 100644 --- a/src/org/wonderly/doclets/TexDoclet.java +++ b/src/org/wonderly/doclets/TexDoclet.java @@ -201,7 +201,7 @@ private static void printComment(Tag[] tags, MethodDoc md) { os.print(HTMLToTex.convert(t.text(), md)); } else { os.print("\\texdocinheritdoc{"); - os.print(overridden.containingClass().qualifiedName()); + os.print(overridden.containingClass().qualifiedName().replace(".", "\\-.")); os.print("}{"); printComment(overridden.inlineTags(), overridden); os.print("}"); From 212804ba33e86cd309a0df785394d691572f092c Mon Sep 17 00:00:00 2001 From: Lukas Boehm Date: Sat, 21 Dec 2013 22:21:06 +0100 Subject: [PATCH 15/21] Fix doclet not showing type dimensions ( = []) at least for return types --- src/org/wonderly/doclets/TexDoclet.java | 1 + 1 file changed, 1 insertion(+) diff --git a/src/org/wonderly/doclets/TexDoclet.java b/src/org/wonderly/doclets/TexDoclet.java index a3b2efb..97b38b0 100644 --- a/src/org/wonderly/doclets/TexDoclet.java +++ b/src/org/wonderly/doclets/TexDoclet.java @@ -519,6 +519,7 @@ private static String typeToString(Type type) { } else { tstring = type.typeName(); } + tstring += type.dimension(); return tstring; } From f5236ca0eeafe9b6afb4e7bfe590b229b5753047 Mon Sep 17 00:00:00 2001 From: Lukas Boehm Date: Sat, 21 Dec 2013 23:54:06 +0100 Subject: [PATCH 16/21] Fix texexclude != texignore --- README.markdown | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.markdown b/README.markdown index abf607f..31105f7 100644 --- a/README.markdown +++ b/README.markdown @@ -8,7 +8,7 @@ applied to by [Matthias Braun](https://github.com/MatzeB). See his github projec My fork adapts the doclet to meet the requirements of our project [lambda-alligatoren](https://github.com/vincent23/lambda-alligatoren). In detail, those are: -* @texexclude tag support +* @texignore tag support * modify the original "preamble.tex" to become an "\\input"-able "docletcommands.tex" (thanks to [@vincent23](https://github.com/vincent23)) * fix a surplus "}" in HTMLtoTex which broke ordered lists From 472a5a46b5a9625956201c4fd058cd103a6a7b5c Mon Sep 17 00:00:00 2001 From: Lukas Boehm Date: Sat, 21 Dec 2013 23:58:44 +0100 Subject: [PATCH 17/21] Clean up docletcommands.tex --- docletcommands.tex | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/docletcommands.tex b/docletcommands.tex index 2f4084c..5e4e843 100644 --- a/docletcommands.tex +++ b/docletcommands.tex @@ -1,4 +1,5 @@ -%\usepackage{xparse} +\usepackage{xparse}% for passing multiple arguments +\usepackage{needspace}% for preventing classe to begin within the lower 7cm of a page % Initially we're not in a package or class \def\packagename{} @@ -7,8 +8,8 @@ \markboth{\protect\packagename{} -- \protect\classname{}}{\protect\packagename{} -- \protect\classname{}} % --------------------------------------------------------------------------- -% TexDoc macros start - everything below this point should be copied to your -% own document and adapted to your style/language if needed +% TexDoc macros start - everything below this point can be +% adapted to your style/language if needed % --------------------------------------------------------------------------- % Environment used to simulate html

@@ -26,7 +27,6 @@ % Argument 2: the name of the class/interface % Argument 3 [opt.]: the name of the superclass % Argument 4 [opt.]: the name of the realized interfaces -% TODO: Probably easier implementation with xparse instead of pgfkeys. Would make substitution ; <-> , unnecessary \NewDocumentEnvironment{texdocclass}{ m m o o }{% \gdef\classname{#2} \subsection[#2]{\texttt{#1 \textbf{#2} @@ -43,8 +43,7 @@ {} {implements #4} }} -% }{\newpage{}} -}{}% removed \newpage +}{\needspace{7cm}} % Environment for class description \newenvironment{texdocclassintro}{ From 634fb9ad10c2e033108c9dce0f6623ee87f17330 Mon Sep 17 00:00:00 2001 From: "Lukas B." Date: Sun, 22 Dec 2013 00:09:24 +0100 Subject: [PATCH 18/21] Update usage section of README --- README.markdown | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/README.markdown b/README.markdown index 31105f7..2dfc6f6 100644 --- a/README.markdown +++ b/README.markdown @@ -27,7 +27,8 @@ Features easily adapt to your own style/document without the need to touch the tools output. * Classes not intended to be part of the generated tex document can be excluded with a dedicated "texignore" tag. -* Shows generalization and realizations +* Shows generalization and realizations ("extends" and "implements") +* Shows dimensions of types, like in "String[][]". * Has doclet specific tex commands outsourced to allow easy integration into existing documents. Commandline Options @@ -46,15 +47,15 @@ Usage javadoc -docletpath texdoclet.jar -doclet org.wonderly.doclets.TexDoclet my.cool.package - This should produce a file docs.tex + This should produce a file docs.tex. See "man javadoc" and the section above for additional command line arguments. -2. You may test the generated output by copying preamble.tex into the current - directory and compiling it with pdflatex (preamble.tex includes docs.tex) +2. You will need to also input "docletcommands.tex" to the preamble of your main document, otherwise + you will get a lot of errors due to missing commands. -3. Copy the definitions inside preamble.tex into the preamble of your own latex - document. Adapt the macros to your style and language needs. - Use \input{docs.tex} inside your document to include the generated - documentation. +3. \\Input the generated "docs.tex" (or the file with the name you specified via -output) at any place within + your document environment. +4. If you like headers, put \\pagestyle{myheadings} in front of the \\input command you just entered. + You can turn off the headers again by re-executing \\pagestyle{plain} or whichever pagestyle you were using before. Original Author/Contact -------------- From aa64d4ce3ed71775a04dda54ff02bdae843e46a6 Mon Sep 17 00:00:00 2001 From: Lukas Boehm Date: Mon, 23 Dec 2013 16:16:40 +0100 Subject: [PATCH 19/21] Small bugfixes in HTMLToTex.java --- src/org/wonderly/doclets/HTMLToTex.java | 15 +++++---------- 1 file changed, 5 insertions(+), 10 deletions(-) diff --git a/src/org/wonderly/doclets/HTMLToTex.java b/src/org/wonderly/doclets/HTMLToTex.java index a243315..1bc1754 100644 --- a/src/org/wonderly/doclets/HTMLToTex.java +++ b/src/org/wonderly/doclets/HTMLToTex.java @@ -230,7 +230,7 @@ private String convertToTex(String input, MethodDoc md) { leave(""); } else if (startsWith("")) { ret.append("\\chapter{"); @@ -238,19 +238,19 @@ private String convertToTex(String input, MethodDoc md) { ret.append("}"); } else if (startsWith("")) { /* nothing */ } else if (startsWith("")) { /* nothing */ } else if (startsWith("")) { /* nothing */ @@ -328,7 +328,7 @@ private String convertToTex(String input, MethodDoc md) { } } else if (startsWith(" Date: Mon, 23 Dec 2013 16:18:38 +0100 Subject: [PATCH 20/21] Fix issues related to Generics (<> parsed as html tags, class parameters not shown...) --- src/org/wonderly/doclets/TexDoclet.java | 103 ++++++++++++++++++++++-- 1 file changed, 97 insertions(+), 6 deletions(-) diff --git a/src/org/wonderly/doclets/TexDoclet.java b/src/org/wonderly/doclets/TexDoclet.java index 97b38b0..eaa854f 100644 --- a/src/org/wonderly/doclets/TexDoclet.java +++ b/src/org/wonderly/doclets/TexDoclet.java @@ -26,6 +26,7 @@ import com.sun.javadoc.Tag; import com.sun.javadoc.ThrowsTag; import com.sun.javadoc.Type; +import com.sun.javadoc.TypeVariable; /** * Note: This version is heavily modified by Matthias Braun @@ -146,6 +147,11 @@ public static boolean start(RootDoc root) { ClassDoc[] classes = root.specifiedClasses(); PackageDoc[] packages = root.specifiedPackages(); + Arrays.sort(packages, new Comparator() { + public int compare(PackageDoc o1, PackageDoc o2) { + return o1.name().compareToIgnoreCase(o2.name()); + } + }); for (PackageDoc pkg : packages) { @@ -258,11 +264,14 @@ private static void printClass(ClassDoc cd) { type = "class"; } - // This string will hold the class' section heading + String name = formatClassDoc(cd); + + // this string will hold the class' section heading String classLine = "\\begin{texdocclass}" + "{" + type + "}" - + "{" + HTMLToTex.convert(cd.name()) + "}"; + + "{" + texEscape(name) + "}"; + // print "extends" fields Type s = cd.superclassType(); if (s != null && !s.toString().equals("java.lang.Object") @@ -275,6 +284,7 @@ private static void printClass(ClassDoc cd) { classLine += "[]"; } + // print "implements" fields Type[] itypes = cd.interfaceTypes(); if (itypes.length > 0) { String realizations = itypes[0].asClassDoc().toString(); @@ -366,9 +376,9 @@ public int compare(FieldDoc o1, FieldDoc o2) { for (FieldDoc f : fields) { os.print("\\texdocfield"); - os.print("{" + HTMLToTex.convert(f.modifiers()) + "}"); - os.print("{" + HTMLToTex.convert(typeToString(f.type())) + "}"); - os.print("{" + HTMLToTex.convert(f.name()) + "}"); + os.print("{" + texEscape(f.modifiers()) + "}"); + os.print("{" + texEscape(typeToString(f.type())) + "}"); + os.print("{" + texEscape(f.name()) + "}"); os.print("{"); printComment(f); os.print("}"); @@ -426,7 +436,7 @@ public int compare(ExecutableMemberDoc o1, ExecutableMemberDoc o2) { os.print("{" + HTMLToTex.convert(member.modifiers()) + "}"); if (member instanceof MethodDoc) { MethodDoc methodDoc = (MethodDoc) member; - os.print("{" + HTMLToTex.convert(typeToString(methodDoc.returnType())) + "}"); + os.print("{" + texEscape(typeToString(methodDoc.returnType())) + "}"); } os.print("{" + HTMLToTex.convert(member.name()) + "}"); os.print("{" + HTMLToTex.convert(formatParameters(member)) + "}"); @@ -502,6 +512,48 @@ private static String formatParameters(ExecutableMemberDoc member) { return res.toString(); } + + /** + * Builds a string with the name and the parameter types of a given ClassDoc. + * + * @param cd the ClassDoc whoes name is to be formatted + * @return a String like "List" in case of a string list + */ + private static String formatClassDoc(ClassDoc cd) { + String name = cd.name(); + TypeVariable[] parameters = cd.typeParameters(); + if (parameters.length > 0) { + name += "<" + formatTypeVariable(parameters[0]); + for (int i = 1; i < parameters.length; i++) { + TypeVariable t = parameters[i]; + name += ", " + formatTypeVariable(t); + } + name +=">"; + } + + return name; + } + + /** + * Formats a given type variable an returns its string representation. + * E.g. "? extends String" for an anonymous TypeVariable that is derived from String + * + * @param t the type variable to be formatted + * @return the formatted string representation + */ + private static String formatTypeVariable(TypeVariable t) { + String result = t.typeName(); + + Type[] bounds = t.bounds(); + if (bounds.length > 0) { + result += " extends " + bounds[0].toString(); + for(int i = 1; i < bounds.length; i++) { + result += ", " + bounds[i].toString(); + } + } + + return result; + } /** * Converts a DocLet type back to java syntax @@ -520,9 +572,48 @@ private static String typeToString(Type type) { tstring = type.typeName(); } tstring += type.dimension(); + return tstring; } + private static String texEscape(String s) { + StringBuilder ret = new StringBuilder(); + for(int i = 0; i < s.length(); i++) { + char c = s.charAt(i); + switch (c) { + case '"': + ret.append("\"'"); + break; + case '_': + case '%': + case '$': + case '#': + ret.append('\\'); + ret.append((char) c); + break; + case '^': /* { */ + ret.append("$\\wedge$"); + break; + case '}': + ret.append("$\\}$"); + break; + case '{': + ret.append("$\\{$"); + break; + case '<': + ret.append("\\textless{}"); + break; + case '>': + ret.append("\\textgreater{}"); + break; + default: + ret.append((char) c); + break; + } + } + return ret.toString(); + } + private static void println(String s) { if (!silent) { System.out.println(s); From 7d3a119805e0029f55cd5fa5270bdb2bf1591e0b Mon Sep 17 00:00:00 2001 From: Lukas Boehm Date: Mon, 23 Dec 2013 16:26:57 +0100 Subject: [PATCH 21/21] Fix class modifiers not being shown --- src/org/wonderly/doclets/TexDoclet.java | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/src/org/wonderly/doclets/TexDoclet.java b/src/org/wonderly/doclets/TexDoclet.java index eaa854f..a2a9403 100644 --- a/src/org/wonderly/doclets/TexDoclet.java +++ b/src/org/wonderly/doclets/TexDoclet.java @@ -264,11 +264,14 @@ private static void printClass(ClassDoc cd) { type = "class"; } + String modifiers = cd.modifiers(); + String name = formatClassDoc(cd); // this string will hold the class' section heading String classLine = "\\begin{texdocclass}" - + "{" + type + "}" + // TODO hacky, uses same tex macro argument as type + + "{" + modifiers + " " + type + "}" + "{" + texEscape(name) + "}"; // print "extends" fields