[dbdoclet] feature request for dbdoclet 0.52 (capability for custom tags)
- From: Haroon Rafique <haroon.rafique@xxxxxxxxxxx>
- To: dbdoclet@xxxxxxxxxxxxx
- Date: Thu, 30 Oct 2003 13:36:19 -0500 (EST)
Hi Michael,
I wanted to explore the possibility of adding custom tag handling
capability to dbdoclet. With Java 1.4, in plain javadoc, you can specify
custom tags by using the -tag command line option:
http://java.sun.com/j2se/1.4.2/docs/tooldocs/solaris/javadoc.html#tag
The ant <javadoc> task, similarly can take <tag> elements, which then get
treated as custom tags.
http://ant.apache.org/manual/CoreTasks/javadoc.html
I have hacked together a first crack at adding this capability to
dbdoclet. Let me begin by saying that you can only arrive at the following
conclusions after reading the code changes:
1. This person is insane
2. He absolutely murdered my precious code
3. This is really neat even though its done in a stupid way
In any case, find attached a diff against 0.51 which adds this capability
(largely untested code, even though it works for me). If the mailing
list doesn't take attachments I can post the diff either inline or
straight to your email address.
Before having this capability my "custom tags" were just disappearing into
thin air. Now I have a way to have the "custom tags" show up with a useful
name in the PDF. This gives me the option of having an ant task like:
<javadoc sourcepath="...."
destdir="...."
packagenames="....">
<classpath refid="compile.classpath"/>
<doclet name="com.mf.doclet.docbook.DocBookDoclet"
path="${dbdoclet.dir}/doclet/lib/dbdoclet.jar">
<param name="-properties" value="dbdoclet.properties"/>
</doclet>
<tag name="struts.action" description="Mapping:" />
<tag name="struts.action-forward" description="ActionForward:" />
<tag name="struts.form" description="Form Name:" />
<tag name="struts.validator" description="Validator:" />
<tag name="web.listener" description="Listener:" />
<tag name="x.generated" description="Generated:" />
<tag name="x.copyright" description="Copyright:" />
</javadoc>
javadoc tags like @struts.action found in source file will end up in the
"Additional Information" section of whichever context they were found in
(overview, packages, methods, fields, etc...). Another thing to note is
that I use the exact same tags (sweet) when generating regular
HTML javadocs.
Brief explanation of the patch follows:
* enables a new command-line option -tag
* keeps track of custom tags in a new LinkedHashMap m_customTagMap
* modifies the signature of addMetaInfo (oops sorry about that)
* only supports tags with scope="all" (in command-line speak that
translates to -tag tagName:a:tagDescription). This means that you cannot
restrict tags to a particular scope
* adds new method addCustomTagEntry in both StyleOne.java and
StyleXSLT.java
Take a look see and let me know if this is worth pursuing further. Works
for me wonderfully, so far.
Regards,
--
Haroon Rafique
<haroon.rafique@xxxxxxxxxxx>
-- Attached file included as plaintext by Ecartis --
-- File: dbdoclet_custom_tags.patch
diff -aur dbdoclet-0.51-src/src/java/com/mf/doclet/docbook/DocBookDoclet.java
dbdoclet-0.51-src.orig/src/java/com/mf/doclet/docbook/DocBookDoclet.java
--- dbdoclet-0.51-src/src/java/com/mf/doclet/docbook/DocBookDoclet.java
2003-10-30 11:29:32.000000000 -0500
+++ dbdoclet-0.51-src.orig/src/java/com/mf/doclet/docbook/DocBookDoclet.java
2003-10-13 17:01:31.000000000 -0400
@@ -44,11 +44,8 @@
import java.util.Arrays;
import java.util.HashMap;
import java.util.Iterator;
-import java.util.LinkedHashSet;
-import java.util.LinkedHashMap;
import java.util.PropertyResourceBundle;
import java.util.ResourceBundle;
-import java.util.Set;
import java.util.StringTokenizer;
import com.mf.doclet.ClassDiagramManager;
@@ -107,7 +104,6 @@
private DocBookTagFactory m_dbfactory = new DocBookTagFactory();
private DocBookProperties m_properties = null;
private Style m_style = null;
- private LinkedHashMap m_customTagMap = new LinkedHashMap();
/**
* The method <code>start</code> is called from within the Doclet
@@ -272,7 +268,7 @@
chapter = new
Chapter(m_res.getString("C_ADDITIONAL_INFORMATION"));
- if
(m_style.addMetaInfo(rootDoc,chapter,m_context,m_customTagMap))
+ if (m_style.addMetaInfo(rootDoc,chapter,m_context))
root.appendChild(chapter);
} // end of if ()
@@ -305,7 +301,7 @@
m_context.setComment(pkgs[i].name() + " p" + "ackage.html");
DbdTransformer.transform(pkgs[i],chapter,m_context);
Sect1 section = new
Sect1(m_res.getString("C_ADDITIONAL_INFORMATION"));
- if
(m_style.addMetaInfo(pkgs[i],section,m_context,m_customTagMap))
+ if (m_style.addMetaInfo(pkgs[i],section,m_context))
chapter.appendChild(section);
writeClasses(chapter, pkgs[i].ordinaryClasses(),
m_res.getString("C_CLASS") + " ", "Classes");
@@ -408,7 +404,7 @@
parent = synopsis;
}
- m_style.addMetaInfo(classes[i],parent,m_context,m_customTagMap);
+ m_style.addMetaInfo(classes[i],parent,m_context);
if ( m_properties.showInheritancePath() ) {
@@ -545,7 +541,7 @@
m_style.addThrowsInfo(memberDoc,section,m_context);
if ( m_properties.showTableMetaInfo() )
-
m_style.addMetaInfo(memberDoc,section,m_context,m_customTagMap);
+ m_style.addMetaInfo(memberDoc,section,m_context);
String comment = memberDoc.commentText();
if ( comment != null && ! comment.trim().equals("") ) {
@@ -613,7 +609,7 @@
m_style.addSerialFieldsInfo(fieldDoc,section,m_context);
if ( m_properties.showTableMetaInfo() == true )
-
m_style.addMetaInfo(fieldDoc,section,m_context,m_customTagMap);
+ m_style.addMetaInfo(fieldDoc,section,m_context);
String comment = fieldDoc.commentText();
if ( comment != null && ! comment.trim().equals("") ) {
@@ -719,7 +715,6 @@
throws InvalidPropertyException
{
HashMap optMap = new HashMap();
- LinkedHashSet customTagStrs = new LinkedHashSet();
String[] opt;
String param;
@@ -739,11 +734,6 @@
optMap.put("docbook.type",opt[1]);
}
- if (opt[0].equals("-tag")) {
- customTagStrs.add(opt);
- logger.debug(" opt[0] == -tag, opt[1] = " + opt[1]);
- }
-
if (opt[0].equals("-title")) {
m_title = opt[1];
}
@@ -802,8 +792,6 @@
}
} // end of for ()
- initCustomTags(customTagStrs);
-
if ( m_properties == null )
m_properties = new DocBookProperties();
@@ -850,67 +838,6 @@
}
/**
- * The method <code>initCustomTags</code>
- * The strings to initialize the custom tags should be in the
- * following format "[tag name]:[tag scope]:[tag heading]". Tags
- * that exist already, overwrite previous tag with new one.
- *
- * @param customTagStrs a two-dimensional array of strings
- * containing -tag arguments
- */
- private void initCustomTags(Set customTagStrs) {
- String[] data;
- StringTokenizer st;
- Iterator it = customTagStrs.iterator();
- String[] args;
-
- // iteratre through all the tags
- while( it.hasNext() ) {
- data = new String[3];
- args = (String[]) it.next();
- // tokenize args[1] on semi-colon
- st = new StringTokenizer(args[1], ":", true);
- logger.debug("Tokens in string " + st.countTokens());
- if( st.countTokens() < 5 || st.countTokens() == 0 ) {
- println("Incorrect tag format! " +
- args[0] + " " + args[1]);
- System.exit(255);
- } else {
- data[0] = st.nextToken();
- st.nextToken();
- data[1] = st.nextToken();
- // For now, we only support scope "a" (all)
- if( !"a".equals(data[1]) ) {
- println("Incorrect tag format! " +
- args[0] + " " + args[1]);
- System.exit(255);
- }
- st.nextToken();
- data[2] = "";
- while( st.hasMoreTokens() ) {
- data[2] += st.nextToken();
- }
- logger.debug("Parsed as " +
- " '" + data[0] + "'" +
- " '" + data[1] + "'" +
- " '" + data[2] + "'");
- if( data[0] != null && data[2] != null ) {
- // retrieve tag name from set
- String tag = (String) m_customTagMap.get(data[0]);
- if( tag == null ) {
- // not already there
- m_customTagMap.put(data[0], data[2]);
- } else {
- // move to back
- m_customTagMap.remove(data[0]);
- m_customTagMap.put(data[0], tag);
- }
- }
- }
- }
- }
-
- /**
* The method <code>optionLength</code>.
*
* @param option a <code>String</code> value
@@ -921,7 +848,6 @@
if( option.equals("-properties") ||
option.equals("-sourcepath") ||
option.equals("-type") ||
- option.equals("-tag") ||
option.equals("-d") ) {
return 2;
}
diff -aur dbdoclet-0.51-src/src/java/com/mf/doclet/docbook/Style.java
dbdoclet-0.51-src.orig/src/java/com/mf/doclet/docbook/Style.java
--- dbdoclet-0.51-src/src/java/com/mf/doclet/docbook/Style.java 2003-10-30
11:28:20.000000000 -0500
+++ dbdoclet-0.51-src.orig/src/java/com/mf/doclet/docbook/Style.java
2003-10-13 17:01:31.000000000 -0400
@@ -36,8 +36,6 @@
import com.sun.javadoc.ExecutableMemberDoc;
import com.sun.javadoc.FieldDoc;
-import java.util.LinkedHashMap;
-
public interface Style
{
public void init(DocBookContext context)
@@ -73,8 +71,7 @@
public boolean addMetaInfo(Doc doc,
DocBookElement parent,
- DocBookContext context,
- LinkedHashMap customTagMap)
+ DocBookContext context)
throws DocletException;
public boolean addParamInfo(ExecutableMemberDoc doc,
diff -aur dbdoclet-0.51-src/src/java/com/mf/doclet/docbook/StyleOne.java
dbdoclet-0.51-src.orig/src/java/com/mf/doclet/docbook/StyleOne.java
--- dbdoclet-0.51-src/src/java/com/mf/doclet/docbook/StyleOne.java
2003-10-30 12:59:32.000000000 -0500
+++ dbdoclet-0.51-src.orig/src/java/com/mf/doclet/docbook/StyleOne.java
2003-10-13 17:01:31.000000000 -0400
@@ -32,9 +32,7 @@
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Iterator;
-import java.util.LinkedHashMap;
import java.util.ResourceBundle;
-import java.util.Set;
import com.mf.doclet.DocletException;
import com.mf.doclet.ReferenceIdCreator;
@@ -83,8 +81,7 @@
public boolean addMetaInfo(Doc doc,
DocBookElement parent,
- DocBookContext context,
- LinkedHashMap customTagMap)
+ DocBookContext context)
throws DocletException
{
if ( doc == null )
@@ -120,7 +117,7 @@
if
(addMetaInfoEntry("@serial",res.getString("C_SERIAL"),doc,context,tbody))
foundSomething = true;
if
(addMetaInfoEntry("@serialData",res.getString("C_SERIAL_DATA"),doc,context,tbody))
foundSomething = true;
if (addSeeAlsoInfo(res.getString("C_SEE_ALSO"),doc,context,tbody))
foundSomething = true;
- if (addCustomTagEntry(customTagMap,doc,context,tbody)) foundSomething
= true;
+
if ( foundSomething == true ) {
parent.
@@ -465,45 +462,7 @@
return true;
}
-
- private boolean addCustomTagEntry(LinkedHashMap customTagMap,
- Doc doc,
- DocBookContext context,
- Tbody tbody)
- throws DocletException
- {
- Tag[] tags;
- boolean found = false;
- Member member;
-
- if( customTagMap == null )
- return false;
-
- Set tagKeys = customTagMap.keySet();
- Iterator it = tagKeys.iterator();
- // iterate on custom tags
- while( it.hasNext() ) {
- String key = (String) it.next();
- String label = (String) customTagMap.get(key);
- tags = doc.tags(key);
- for ( int i=0; i<tags.length; i++ ) {
-
- SimpleList list = new SimpleList();
- list.setType(list.INLINE);
- member = new Member();
-
- context.setComment("addCustomTag " + tags[i].name());
- DbdTransformer.transform(tags[i], member, context);
-
- list.appendChild(member.toDocbook());
-
- tbody.addRow(label,list.toDocbook());
- found = true;
- } // end of for ()
- } // end of while ()
-
- return found;
- }
+
private boolean addMetaInfoEntry(String tagName,
String label,
diff -aur dbdoclet-0.51-src/src/java/com/mf/doclet/docbook/StyleXSLT.java
dbdoclet-0.51-src.orig/src/java/com/mf/doclet/docbook/StyleXSLT.java
--- dbdoclet-0.51-src/src/java/com/mf/doclet/docbook/StyleXSLT.java
2003-10-30 12:22:10.000000000 -0500
+++ dbdoclet-0.51-src.orig/src/java/com/mf/doclet/docbook/StyleXSLT.java
2003-10-13 17:01:31.000000000 -0400
@@ -40,9 +40,7 @@
import java.util.ArrayList;
import java.util.HashMap;
import java.util.Iterator;
-import java.util.LinkedHashMap;
import java.util.ResourceBundle;
-import java.util.Set;
import java.util.Stack;
import javax.xml.transform.Transformer;
import javax.xml.transform.TransformerFactory;
@@ -566,8 +564,7 @@
*/
public boolean addMetaInfo(Doc doc,
DocBookElement parent,
- DocBookContext context,
- LinkedHashMap customTagMap)
+ DocBookContext context)
throws DocletException
{
if ( doc == null )
@@ -619,9 +616,6 @@
if ( addDeprecatedInfo(doc,context,meta) )
foundSomething = true;
- if ( addCustomTagEntry(customTagMap,doc,context,meta) )
- foundSoumething = true;
-
HashMap parameters = new HashMap();
StringWriter buffer = new StringWriter();
@@ -826,40 +820,6 @@
}
}
- private boolean addCustomTagEntry(LinkedHashMap customTagMap,
- Doc doc,
- DocBookContext context,
- Meta meta)
- throws DocletException
- {
- Tag[] tags;
- Para para;
- boolean found = false;
-
- if( customTagMap == null )
- return false;
-
- Set tagKeys = customTagMap.keySet();
- Iterator it = tagKeys.iterator();
- // iterate on custom tags
- while( it.hasNext() ) {
- String key = (String) it.next();
- String label = (String) customTagMap.get(key);
- tags = doc.tags(key);
- for ( int i=0; i<tags.length; i++ ) {
- para = new Para();
- context.setComment("addCustomTag " + tags[i].name());
- DbdTransformer.transform(tags[i], para, context);
-
- meta.appendChild(new Entry().
- appendChild(new Label(label)).
- appendChild(new Description(para.toDocbook(true))));
- found = true;
- } // end of for ()
- } // end of while ()
- return found;
- }
-
private boolean addMetaInfoEntry(String tagName,
String label,
Doc doc,
Other related posts:
- » [dbdoclet] feature request for dbdoclet 0.52 (capability for custom tags)