This patch provides support for two custom taglets for javadocs in xerces: @xerces.internal and @xerces.experimental.
These tags should be applied to any xerces classes/interfaces or methods that are internal (not to be used by end users)
or experimental (highly likely to change or deleted) in the same way as @deprecated is used.
A taglets.jar file to be placed in tools\bin directory will contain the compiled version of these taglets and used for the builds.
build.xml changes coming soon.
Ankit Pasricha
XML Parser Development
IBM Toronto Lab
8200 Warden Avenue, Ontario L6G 1C7
Phone: (905) 413 4941
taglets.jar
Description: Binary data
Index: bin/taglets.opt =================================================================== RCS file: bin/taglets.opt diff -N bin/taglets.opt --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ bin/taglets.opt 1 Jan 1970 00:00:00 -0000 @@ -0,0 +1,2 @@ +-taglet org.apache.xerces.util.ExperimentalTaglet +-taglet org.apache.xerces.util.InternalTaglet Index: src/ExperimentalTaglet.java =================================================================== RCS file: src/ExperimentalTaglet.java diff -N src/ExperimentalTaglet.java --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ src/ExperimentalTaglet.java 1 Jan 1970 00:00:00 -0000 @@ -0,0 +1,129 @@ +/* + * Copyright 2004 The Apache Software Foundation. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.apache.xerces.util; + +import java.util.Map; + +import com.sun.javadoc.Tag; +import com.sun.tools.doclets.Taglet; + +/** + * This class provides support for a 'xerces.experimental' tag + * in javadoc comments. The tag creates a warning in the generated + * html for users. + * + * @author Ankit Pasricha, IBM + */ +public class ExperimentalTaglet implements Taglet { + + private static final String NAME = "xerces.experimental"; + private static final String HEADER = "EXPERIMENTAL:"; + /* (non-Javadoc) + * @see com.sun.tools.doclets.Taglet#inConstructor() + */ + public boolean inConstructor() { + return false; + } + + /* (non-Javadoc) + * @see com.sun.tools.doclets.Taglet#inField() + */ + public boolean inField() { + return false; + } + + /* (non-Javadoc) + * @see com.sun.tools.doclets.Taglet#inMethod() + */ + public boolean inMethod() { + return true; + } + + /* (non-Javadoc) + * @see com.sun.tools.doclets.Taglet#inOverview() + */ + public boolean inOverview() { + return true; + } + + /* (non-Javadoc) + * @see com.sun.tools.doclets.Taglet#inPackage() + */ + public boolean inPackage() { + return false; + } + + /* (non-Javadoc) + * @see com.sun.tools.doclets.Taglet#inType() + */ + public boolean inType() { + return true; + } + + /* (non-Javadoc) + * @see com.sun.tools.doclets.Taglet#isInlineTag() + */ + public boolean isInlineTag() { + return false; + } + + /* (non-Javadoc) + * @see com.sun.tools.doclets.Taglet#getName() + */ + public String getName() { + return NAME; + } + + /* (non-Javadoc) + * @see com.sun.tools.doclets.Taglet#toString(com.sun.javadoc.Tag) + */ + public String toString(Tag arg0) { + return "<DT><H1 style=\"font-size:150%\">" + HEADER + "</H1><DD>" + + "This interface should not be considered stable. It is likely to be altered or replaced in the future.<br/>" + + "<I>" + arg0.text() + "</I></DD>\n"; + } + + /* (non-Javadoc) + * @see com.sun.tools.doclets.Taglet#toString(com.sun.javadoc.Tag[]) + */ + public String toString(Tag[] tags) { + if (tags.length == 0) { + return null; + } + String result = "\n<DT><H1 style=\"font-size:150%\">" + HEADER + "</H1><DD>"; + result += "This interface should not be considered stable. It is likely it may be altered or replaced in the future."; + result += "<I>"; + for (int i = 0; i < tags.length; i++) { + result += "<br/>"; + result += tags[i].text(); + } + return result + "</I></DD>\n"; + } + + /** + * Register this Taglet. + * @param tagletMap the map to register this tag to. + */ + public static void register(Map tagletMap) { + ExperimentalTaglet tag = new ExperimentalTaglet(); + Taglet t = (Taglet) tagletMap.get(tag.getName()); + if (t != null) { + tagletMap.remove(tag.getName()); + } + tagletMap.put(tag.getName(), tag); + } + +} Index: src/InternalTaglet.java =================================================================== RCS file: src/InternalTaglet.java diff -N src/InternalTaglet.java --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ src/InternalTaglet.java 1 Jan 1970 00:00:00 -0000 @@ -0,0 +1,129 @@ +/* + * Copyright 2004 The Apache Software Foundation. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.apache.xerces.util; + +import java.util.Map; + +import com.sun.javadoc.Tag; +import com.sun.tools.doclets.Taglet; + +/** + * This class provides support for a 'xerces.internal' tag + * in javadoc comments. The tag creates a warning in the generated + * html for users. + * + * @author Ankit Pasricha, IBM + */ +public class InternalTaglet implements Taglet { + + private static final String NAME = "xerces.internal"; + private static final String HEADER = "INTERNAL:"; + /* (non-Javadoc) + * @see com.sun.tools.doclets.Taglet#inConstructor() + */ + public boolean inConstructor() { + return false; + } + + /* (non-Javadoc) + * @see com.sun.tools.doclets.Taglet#inField() + */ + public boolean inField() { + return false; + } + + /* (non-Javadoc) + * @see com.sun.tools.doclets.Taglet#inMethod() + */ + public boolean inMethod() { + return true; + } + + /* (non-Javadoc) + * @see com.sun.tools.doclets.Taglet#inOverview() + */ + public boolean inOverview() { + return true; + } + + /* (non-Javadoc) + * @see com.sun.tools.doclets.Taglet#inPackage() + */ + public boolean inPackage() { + return false; + } + + /* (non-Javadoc) + * @see com.sun.tools.doclets.Taglet#inType() + */ + public boolean inType() { + return true; + } + + /* (non-Javadoc) + * @see com.sun.tools.doclets.Taglet#isInlineTag() + */ + public boolean isInlineTag() { + return false; + } + + /* (non-Javadoc) + * @see com.sun.tools.doclets.Taglet#getName() + */ + public String getName() { + return NAME; + } + + /* (non-Javadoc) + * @see com.sun.tools.doclets.Taglet#toString(com.sun.javadoc.Tag) + */ + public String toString(Tag arg0) { + return "<DT><H1 style=\"font-size:110%\">" + HEADER + "</H1><DD>" + + "This type should not be directly used by the user. The methods/fields defined can be altered or removed at any time.<br/>" + + "<I>" + arg0.text() + "</I></DD>\n"; + } + + /* (non-Javadoc) + * @see com.sun.tools.doclets.Taglet#toString(com.sun.javadoc.Tag[]) + */ + public String toString(Tag[] tags) { + if (tags.length == 0) { + return null; + } + String result = "\n<DT><H1 style=\"font-size:110%\">" + HEADER + "</H1><DD>"; + result += "This type should not be directly used by the user. The methods/fields defined can be altered or removed at any time."; + result += "<I>"; + for (int i = 0; i < tags.length; i++) { + result += "<br/>"; + result += tags[i].text(); + } + return result + "</I></DD>\n"; + } + + /** + * Register this Taglet. + * @param tagletMap the map to register this tag to. + */ + public static void register(Map tagletMap) { + InternalTaglet tag = new InternalTaglet(); + Taglet t = (Taglet) tagletMap.get(tag.getName()); + if (t != null) { + tagletMap.remove(tag.getName()); + } + tagletMap.put(tag.getName(), tag); + } + +}
--------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
