[med-svn] [Git][med-team/libsbml][master] Deal with issue in doclets by removing docs/src/SBMLDoclet.java
Andreas Tille
gitlab at salsa.debian.org
Mon May 21 06:37:28 BST 2018
Andreas Tille pushed to branch master at Debian Med / libsbml
Commits:
42c0344c by Andreas Tille at 2018-05-21T06:50:46+02:00
Deal with issue in doclets by removing docs/src/SBMLDoclet.java
- - - - -
3 changed files:
- debian/changelog
- + debian/patches/remove_SBMLDoclet.patch
- debian/patches/series
Changes:
=====================================
debian/changelog
=====================================
--- a/debian/changelog
+++ b/debian/changelog
@@ -7,7 +7,7 @@ libsbml (5.16.0+dfsg-3) UNRELEASED; urgency=medium
[ Andreas Tille ]
* Point Vcs fields to salsa.debian.org
* Standards-Version: 4.1.4
- * Deal with issue in doclets
+ * Deal with issue in doclets by removing docs/src/SBMLDoclet.java
-- Andreas Tille <tille at debian.org> Mon, 14 May 2018 10:55:58 +0200
=====================================
debian/patches/remove_SBMLDoclet.patch
=====================================
--- /dev/null
+++ b/debian/patches/remove_SBMLDoclet.patch
@@ -0,0 +1,533 @@
+Description: Deal with issue in doclets by removing docs/src/SBMLDoclet.java
+Bug-Debian: https://bugs.debian.org/896531
+Author: Andreas Tille <tille at debian.org>
+Last-Update: Mon, 14 May 2018 10:55:58 +0200
+
+--- a/docs/src/SBMLDoclet.java
++++ /dev/null
+@@ -1,525 +0,0 @@
+-/**
+- * @file SBMLDoclet.java
+- * @brief Exclude files, allow tag "@internal", and more.
+- * @author Michael Hucka
+- *
+- * <!-- -----------------------------------------------------------------------
+- * Portions of this code are under the following copyright terms:
+- *
+- * Copyright 2004 Sun Microsystems, Inc. All Rights Reserved.
+- *
+- * Redistribution and use in source and binary forms, with or without
+- * modification, are permitted provided that the following conditions are met:
+- *
+- * - Redistribution of source code must retain the above copyright notice,
+- * this list of conditions and the following disclaimer.
+- *
+- * - Redistribution in binary form must reproduce the above copyright notice,
+- * this list of conditions and the following disclaimer in the documentation
+- * and/or other materials provided with the distribution.
+- *
+- * Neither the name of Sun Microsystems, Inc. nor the names of contributors may be
+- * used to endorse or promote products derived from this software without specific
+- * prior written permission.
+- *
+- * This software is provided "AS IS," without a warranty of any kind. ALL EXPRESS
+- * OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED
+- * WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT,
+- * ARE HEREBY EXCLUDED. SUN MICROSYSTEMS, INC. ("SUN") AND ITS LICENSORS SHALL NOT
+- * BE LIABLE FOR ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING
+- * OR DISTRIBUTING THIS SOFTWARE OR ITS DERIVATIVES. IN NO EVENT WILL SUN OR ITS
+- * LICENSORS BE LIABLE FOR ANY LOST REVENUE, PROFIT OR DATA, OR FOR DIRECT, INDIRECT,
+- * SPECIAL, CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED AND
+- * REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF THE USE OF OR INABILITY
+- * TO USE THIS SOFTWARE, EVEN IF SUN HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
+- * DAMAGES.
+- *
+- * You acknowledge that this software is not designed, licensed or intended for
+- * use in the design, construction, operation or maintenance of any nuclear facility.
+- *
+- * ------------------------------------------------------------------------ -->
+- *
+- * Portions of this code was originally obtained on 24 Feb. 2008 from
+- * http://java.sun.com/developer/JDCTechTips/2004/tt1214.html
+- * Author: Jamie Ho, Sun Microsystems, Inc.
+- *
+- * The following documentation was copied from that page.
+- *
+- * java -classpath <path to doclet and path to tools.jar>
+- * ExcludeDoclet -excludefile <path to exclude file> <javadoc options>
+- *
+- * In response to the command, the validOptions method of the Doclet class
+- * looks for the -excludefile option. If it finds it, the method reads the
+- * contents of the exclude file -- these are the set of classes and
+- * packages to ignore. Then the start method is called. As each class or
+- * package is processed, the method throws away the classes and packages in
+- * the exclude set. The doclet includes the optionLength method, this
+- * allows the doclet to run under both J2SE 1.4 and 5.0.
+- *
+- * Compile the doclet as follows:
+- *
+- * javac -classpath tools.jar ExcludeDoclet.java
+- *
+- * Replace tools.jar with the appropriate location of your JDK
+- * installation. For example, if you're running in the Windows environment
+- * and your JDK is installed in the c:\jdk1.5.0 directory, specify
+- * c:\jdk1.5.0\lib\tools.jar.
+- *
+- * Next, create a file such as skip.txt to identify which classes to
+- * skip. For this example, run ExcludeDoclet with the standard JDK
+- * classes, and ignore a set in the java.lang package:
+- *
+- * java.lang.Math
+- * java.lang.Long
+- * java.lang.InternalError
+- * java.lang.InterruptedException
+- * java.lang.Iterable
+- * java.lang.LinkageError
+- *
+- * Then run the following command (on one line):
+- *
+- * java -classpath .;c:\jdk1.5.0\lib\tools.jar ExcludeDoclet
+- * -d docs -excludefile skip.txt -sourcepath c:\jdk1.5.0\src
+- * -source 1.5 java.lang
+- *
+- * The command will generate the javadoc for the java.lang package,
+- * excluding the six classes and interfaces identified in skip.txt.
+- *
+- * ----------------------------------------------------------------------------
+- * Additional notes (M. Hucka):
+- * - "tools.jar" is called "classes.jar" on MacOS and it's located in
+- * /System/Library/Frameworks/JavaVM.framework/Classes/classes.jar
+- * See http://lists.apple.com/archives/java-dev/2002/Jun/msg00901.html
+- *
+- * - 2008-02-25 I made a small tweak to the diagnostic msgs printed by start()
+- *
+- * - 2011-11-03 I added the @exclude tag processing code written by
+- * Chris Nokleberg and made available from the following URL:
+- * http://www.sixlegs.com/blog/java/exclude-javadoc-tag.html The page was
+- * dated 22 Feb 2005. The page stated that the code is in the public
+- * domain. The file was originally also named ExcludeDoclet.java. What I
+- * did is take the code and make it a subclass within this file, and took
+- * the bulk of the previous doclet code and put it in *another* subclass in
+- * this file, then hooked them together through the main() method.
+- *
+- * - 2011-11-08 Changed @exclude to @internal, which is what Doxygen uses
+- * for the purpose we're using this for.
+- */
+-
+-import java.io.*;
+-import java.util.*;
+-import java.lang.reflect.*;
+-import com.sun.tools.doclets.standard.Standard;
+-import com.sun.tools.javadoc.Main;
+-import com.sun.javadoc.*;
+-
+-
+-/**
+- * A wrapper for Javadoc. Accepts additional options:
+- *
+- * * "-excludefile": specifies which classes and packages should be excluded
+- * from the output.
+- *
+- * * "-listskipped": print things that get skipped because they are SWIG
+- * things we don't want in the documentation.
+- *
+- * @author Jamie Ho
+- * @author Michael Hucka
+- */
+-public class SBMLDoclet extends Doclet
+-{
+- private static List m_args = new ArrayList();
+- private static Set m_excludeSet = new HashSet();
+- static boolean m_list_skipped = false;
+-
+- /**
+- * First executes the doclet that exclude files.
+- * Then it executes the doclet that processes the classes and excludes
+- * things marked with @exclude.
+- *
+- * @param args the Javadoc arguments from the command line
+- */
+- public static void main(String[] args)
+- {
+- String name;
+-
+- name = FileExclusionDoclet.class.getName();
+- Main.execute(name, name, args);
+-
+- name = SBMLProcessingDoclet.class.getName();
+- Main.execute(name, name, (String[]) m_args.toArray(new String[] {}));
+- }
+-
+- /* --------------------------------------------------------------------- */
+-
+- /**
+- * File exclusion handler class.
+- *
+- * This code was originally taken from:
+- * @(#)SBMLDoclet.java 1.1 04/08/31
+- * http://java.sun.com/developer/JDCTechTips/2004/tt1214.html
+- */
+- public static class FileExclusionDoclet
+- extends Doclet
+- {
+- /**
+- * Iterate through the documented classes and remove the ones that should
+- * be excluded.
+- *
+- * @param root the initial RootDoc (before filtering).
+- */
+- public static boolean start(RootDoc root)
+- {
+- root.printNotice("SBMLDoclet removing excluded source files...");
+- ClassDoc[] classes = root.classes();
+- for (int i = 0; i < classes.length; i++) {
+- if (m_excludeSet.contains(classes[i].qualifiedName()) ||
+- m_excludeSet.contains(classes[i].containingPackage().name())) {
+- root.printNotice("Excluding " + classes[i].qualifiedName());
+- continue;
+- }
+- m_args.add(classes[i].position().file().getPath());
+- }
+- return true;
+- }
+-
+- /**
+- * Let every option be valid. The real validation happens in the
+- * standard doclet, not here. Remove the "-excludefile" and
+- * "-subpackages" options because they are not needed by the standard
+- * doclet. Similarly, process SBMLDoclet's -listexcludes flag here
+- * and also remove it.
+- *
+- * @param options the options from the command line
+- * @param reporter the error reporter
+- */
+- public static boolean validOptions(String[][] options,
+- DocErrorReporter reporter)
+- {
+- for (int i = 0; i < options.length; i++) {
+- if (options[i][0].equalsIgnoreCase("-excludefile")) {
+- try {
+- readExcludeFile(options[i][1]);
+- } catch (Exception e) {
+- e.printStackTrace();
+- }
+- continue;
+- }
+- if (options[i][0].equals("-subpackages")) {
+- continue;
+- }
+- if (options[i][0].equals("-listskipped")) {
+- m_list_skipped = true;
+- continue;
+- }
+- for (int j = 0; j < options[i].length; j++) {
+- m_args.add(options[i][j]);
+- }
+- }
+- return true;
+- }
+-
+- /**
+- * Parse the file that specifies which classes and packages to exclude from
+- * the output. You can write comments in this file by starting the line with
+- * a '#' character.
+- *
+- * @param filePath the path to the exclude file.
+- */
+- private static void readExcludeFile(String filePath)
+- throws Exception
+- {
+- LineNumberReader reader = new LineNumberReader(new FileReader(filePath));
+- String line;
+- while ((line = reader.readLine()) != null) {
+- if (line.trim().startsWith("#"))
+- continue;
+- m_excludeSet.add(line.trim());
+- }
+- }
+-
+- /**
+- * Method required to validate the length of the given option. This is a
+- * bit ugly but the options must be hard coded here. Otherwise, Javadoc
+- * will throw errors when parsing options. We could delegate to the
+- * Standard doclet when computing option lengths, but then this doclet would
+- * be dependent on the version of J2SE used. Prefer to hard code options
+- * here so that this doclet can be used with 1.4.x or 1.5.x .
+- *
+- * @param option the option to compute the length for
+- */
+- public static int optionLength(String option)
+- {
+- if (option.equalsIgnoreCase("-excludefile")) {
+- return 2;
+- }
+-
+- //General options
+- if (option.equals("-author") ||
+- option.equals("-docfilessubdirs") ||
+- option.equals("-keywords") ||
+- option.equals("-linksource") ||
+- option.equals("-nocomment") ||
+- option.equals("-nodeprecated") ||
+- option.equals("-nosince") ||
+- option.equals("-notimestamp") ||
+- option.equals("-quiet") ||
+- option.equals("-xnodate") ||
+- option.equals("-version")) {
+- return 1;
+- } else if (option.equals("-d") ||
+- option.equals("-docencoding") ||
+- option.equals("-encoding") ||
+- option.equals("-excludedocfilessubdir") ||
+- option.equals("-link") ||
+- option.equals("-sourcetab") ||
+- option.equals("-noqualifier") ||
+- option.equals("-output") ||
+- option.equals("-sourcepath") ||
+- option.equals("-tag") ||
+- option.equals("-taglet") ||
+- option.equals("-tagletpath")) {
+- return 2;
+- } else if (option.equals("-group") ||
+- option.equals("-linkoffline")) {
+- return 3;
+- }
+-
+- //Standard doclet options
+- option = option.toLowerCase();
+- if (option.equals("-nodeprecatedlist") ||
+- option.equals("-noindex") ||
+- option.equals("-notree") ||
+- option.equals("-nohelp") ||
+- option.equals("-splitindex") ||
+- option.equals("-serialwarn") ||
+- option.equals("-use") ||
+- option.equals("-nonavbar") ||
+- option.equals("-nooverview")) {
+- return 1;
+- } else if (option.equals("-footer") ||
+- option.equals("-header") ||
+- option.equals("-packagesheader") ||
+- option.equals("-doctitle") ||
+- option.equals("-windowtitle") ||
+- option.equals("-bottom") ||
+- option.equals("-helpfile") ||
+- option.equals("-stylesheetfile") ||
+- option.equals("-charset") ||
+- option.equals("-overview")) {
+- return 2;
+- } else {
+- return 0;
+- }
+- }
+- }
+-
+- /* --------------------------------------------------------------------- */
+-
+- /**
+- * Our own processing doclet.
+- *
+- * The code to handle @internal was originally taken from:
+- * http://www.sixlegs.com/blog/java/exclude-javadoc-tag.html
+- * Author: Chris Nokleberg.
+- * It looks for @internal in documentation strings and excludes the
+- * method or class marked by it.
+- *
+- * This has added code to substitute a documentation string for
+- * delete(). I have not been able to find a way to do otherwise. SWIG
+- * will simply not let me attach doc strings to delete() at all, so I
+- * have to do it outside. Grafting the code here was the best
+- * solution, though this code could stand to be reorganized and
+- * modularized better.
+- */
+-
+- public static class SBMLProcessingDoclet
+- extends Doclet
+- {
+- private static RootDoc the_root;
+-
+- public static boolean validOptions(String[][] options,
+- DocErrorReporter reporter)
+- {
+- return Standard.validOptions(options, reporter);
+- }
+-
+- public static int optionLength(String option)
+- {
+- return Standard.optionLength(option);
+- }
+-
+- public static boolean start(RootDoc root)
+- {
+- the_root = root;
+- return Standard.start((RootDoc) process(root, RootDoc.class));
+- }
+-
+- private static boolean markedInternal(Doc doc)
+- {
+- if (doc instanceof ProgramElementDoc)
+- {
+- ProgramElementDoc pdoc = (ProgramElementDoc) doc;
+- if (pdoc.containingPackage().tags("internal").length > 0)
+- return true;
+- }
+- return doc.tags("internal").length > 0;
+- }
+-
+- private static boolean isSWIGWrapper(Doc doc)
+- {
+- if (doc instanceof ProgramElementDoc)
+- {
+- ProgramElementDoc pdoc = (ProgramElementDoc) doc;
+- if (pdoc.containingPackage().name().startsWith("SWIGTYPE_p"))
+- return true;
+- }
+- return doc.name().startsWith("SWIGTYPE_p");
+- }
+-
+- private static boolean isJNIclass(Doc doc)
+- {
+- if (doc instanceof ProgramElementDoc)
+- {
+- ProgramElementDoc pdoc = (ProgramElementDoc) doc;
+- if (pdoc.containingPackage().name().startsWith("libsbmlJNI"))
+- return true;
+- }
+- return doc.name().startsWith("libsbmlJNI");
+- }
+-
+- private static boolean isSWIGOwnershipMethod(Doc doc)
+- {
+- if (doc instanceof ProgramElementDoc)
+- {
+- ProgramElementDoc pdoc = (ProgramElementDoc) doc;
+- if (pdoc.qualifiedName().endsWith("swigReleaseOwnership")
+- || pdoc.qualifiedName().endsWith("swigTakeOwnership"))
+- return true;
+- }
+- return (doc.isMethod()
+- && (doc.name().equals("swigReleaseOwnership")
+- || doc.name().equals("swigTakeOwnership")));
+- }
+-
+- private static boolean isDeleteMethod(Doc doc)
+- {
+- if (doc instanceof ProgramElementDoc)
+- {
+- ProgramElementDoc pdoc = (ProgramElementDoc) doc;
+- if (pdoc.qualifiedName().endsWith("delete"))
+- return true;
+- }
+- return (doc.isMethod() && doc.name().equals("delete"));
+- }
+-
+- private static Object process(Object obj, Class expect)
+- {
+- if (obj == null)
+- return null;
+- Class cls = obj.getClass();
+- if (cls.getName().startsWith("com.sun."))
+- {
+- return Proxy.newProxyInstance(cls.getClassLoader(),
+- cls.getInterfaces(),
+- new InternalTagHandler(obj));
+- }
+- else if (obj instanceof Object[])
+- {
+- Class componentType = expect.getComponentType();
+- Object[] array = (Object[])obj;
+- List list = new ArrayList(array.length);
+- for (int i = 0; i < array.length; i++)
+- {
+- Object entry = array[i];
+- if (entry instanceof Doc)
+- {
+- Doc item = (Doc) entry;
+-
+- if (markedInternal(item))
+- continue;
+-
+- if (isSWIGWrapper(item) || isJNIclass(item) ||
+- isSWIGOwnershipMethod(item))
+- {
+- if (m_list_skipped)
+- {
+- the_root.printNotice("SBMLDoclet: skipping "
+- + item);
+- }
+- continue;
+- }
+-
+- if (isDeleteMethod(item))
+- {
+- item.setRawCommentText(
+- "Explicitly deletes the underlying native object." +
+- "<p>" +
+- "In general, application software will not need to call this method " +
+- "directly. The Java language binding for libSBML is implemented as a " +
+- "language wrapper that provides a Java interface to libSBML's " +
+- "underlying C++/C code. Some of the Java methods return objects that " +
+- "are linked to objects created not by Java code, but by C++ code. The " +
+- "Java objects wrapped around them will be deleted when the garbage " +
+- "collector invokes the corresponding C++ <code>finalize()</code> methods for the " +
+- "objects. The <code>finalize()</code> methods in turn call " +
+- "the {@link #delete()} method on the libSBML object. " +
+- "<p>" +
+- "This method is exposed in case calling programs want to ensure that " +
+- "the underlying object is freed immediately, and not at some arbitrary " +
+- "time determined by the Java garbage collector. In normal usage, " +
+- "callers do not need to invoke {@link #delete()} themselves.");
+- }
+- }
+- list.add(process(entry, componentType));
+- }
+- return list.toArray((Object[])Array.newInstance(componentType, list.size()));
+- }
+- else
+- {
+- return obj;
+- }
+- }
+-
+- private static class InternalTagHandler
+- implements InvocationHandler
+- {
+- private Object target;
+-
+- public InternalTagHandler(Object target)
+- {
+- this.target = target;
+- }
+-
+- public Object invoke(Object proxy, Method method, Object[] args)
+- throws Throwable
+- {
+- if (args != null)
+- {
+- String mName = method.getName();
+- if (mName.equals("compareTo") || mName.equals("equals") ||
+- mName.equals("overrides") || mName.equals("subclassOf"))
+- {
+- args[0] = unwrap(args[0]);
+- }
+- }
+- try
+- {
+- return process(method.invoke(target, args), method.getReturnType());
+- }
+- catch (InvocationTargetException e)
+- {
+- throw e.getTargetException();
+- }
+- }
+-
+- private Object unwrap(Object proxy)
+- {
+- if (proxy instanceof Proxy)
+- return ((InternalTagHandler) Proxy.getInvocationHandler(proxy)).target;
+- return proxy;
+- }
+- }
+- }
+-
+-}
=====================================
debian/patches/series
=====================================
--- a/debian/patches/series
+++ b/debian/patches/series
@@ -6,4 +6,5 @@ swig-3.x.patch
mips-compile-with-O1.patch
# fix_cmake.patch # just warnings - ignore
javadoc_java9.patch
-javadoc.patch
+# javadoc.patch
+remove_SBMLDoclet.patch
View it on GitLab: https://salsa.debian.org/med-team/libsbml/commit/42c0344c364ec3f717cb02fa38f16a3b629644bf
---
View it on GitLab: https://salsa.debian.org/med-team/libsbml/commit/42c0344c364ec3f717cb02fa38f16a3b629644bf
You're receiving this email because of your account on salsa.debian.org.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://alioth-lists.debian.net/pipermail/debian-med-commit/attachments/20180521/ab942b40/attachment-0001.html>
More information about the debian-med-commit
mailing list