Skip to content

Commit 5595079

Browse files
sansumbrellasansumbrella
committed
@see_external tag implemented. See todo.txt for more info. Allows for proper documentation of events in libraries.
1 parent 1963610 commit 5595079

File tree

9 files changed

+208
-106
lines changed

9 files changed

+208
-106
lines changed

‎java_generate/ReferenceGenerator/bin/ProcessingWeblet.class‎

29 Bytes
Binary file not shown.

‎java_generate/ReferenceGenerator/bin/writers/BaseWriter.class‎

897 Bytes
Binary file not shown.

‎java_generate/ReferenceGenerator/bin/writers/Shared.class‎

1.46 KB
Binary file not shown.

‎java_generate/ReferenceGenerator/bin/writers/XMLReferenceWriter.class‎

-719 Bytes
Binary file not shown.

‎java_generate/ReferenceGenerator/src/ProcessingWeblet.java‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,6 @@ public class ProcessingWeblet extends Standard {
3939
private static String verboseFlag = "-noisy";
4040
private static String rootFlag = "-rootclass";
4141
private static String xmlDescriptionFlag = "-includeXMLTag";
42-
private static String exceptionsList = "";
4342
private static IndexWriter indexWriter;
4443

4544
public static boolean start(RootDoc root) {
@@ -55,10 +54,11 @@ public static boolean start(RootDoc root) {
5554

5655
System.out.println("===Source code @webref files written.===");
5756

58-
if (!exceptionsList.equals("")) { // need to get something back from
57+
if (!Shared.i().getIncludeDirectory().equals(""))
58+
{ // need to get something back from
5959
// this to create index
6060
System.out.println("\n===Writing XML-sourced reference.===");
61-
XMLReferenceWriter.write(exceptionsList, indexWriter);
61+
XMLReferenceWriter.write( Shared.i().getIncludeDirectory(), indexWriter);
6262
System.out.println("===Include directory files written.===");
6363
}
6464
System.out.println("\n===Telling the index to write itself.===");
@@ -86,7 +86,7 @@ private static void setConfig(String[][] configOptions) {
8686
Shared.i().setOutputDirectory(option[1]);
8787
} else if (option[0].equals(exceptionsFlag)) {
8888
// write out files based on exceptions index
89-
exceptionsList = option[1];
89+
Shared.i().setIncludeDirectory( option[1] );
9090
} else if (option[0].equals(imagesFlag)) {
9191
Shared.i().setImageDirectory(option[1]);
9292
} else if( option[0].equals(localFlag) )

‎java_generate/ReferenceGenerator/src/writers/BaseWriter.java‎

Lines changed: 55 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -594,7 +594,7 @@ protected static ArrayList<HashMap<String, String>> parseParameters(ExecutableMe
594594
return ret;
595595
}
596596

597-
protected static String getRelated(ProgramElementDoc doc) throws IOException
597+
protected static String getRelated( ProgramElementDoc doc ) throws IOException
598598
{
599599
TemplateWriter templateWriter = new TemplateWriter();
600600
ArrayList<HashMap<String, String>> vars = new ArrayList<HashMap<String,String>>();
@@ -604,7 +604,8 @@ protected static String getRelated(ProgramElementDoc doc) throws IOException
604604
if( doc.isMethod() || doc.isField() )
605605
{
606606
ClassDoc containingClass = doc.containingClass();
607-
// consider only doing this if we aren't in the core, although the core would protect against certain errors
607+
// consider only doing this if we aren't in the core
608+
// doing this in the core protects against errant references to PGraphics
608609
// if( !containingClass.name().equalsIgnoreCase("PApplet") )
609610
{
610611
for( MethodDoc m : containingClass.methods() )
@@ -624,6 +625,7 @@ protected static String getRelated(ProgramElementDoc doc) throws IOException
624625
}
625626
}
626627

628+
// add link to each @see item
627629
for( SeeTag tag : doc.seeTags() ){
628630
HashMap<String, String> map = new HashMap<String, String>();
629631

@@ -645,6 +647,57 @@ protected static String getRelated(ProgramElementDoc doc) throws IOException
645647
vars.add(map);
646648
}
647649
}
650+
651+
// add link to each @see_external item
652+
for( Tag tag : doc.tags( Shared.i().getSeeAlsoTagName() ) )
653+
{
654+
// get xml for method
655+
String filename = tag.text() + ".xml";
656+
String basePath = Shared.i().getXMLDirectory();
657+
File f = new File( basePath + filename );
658+
659+
if( ! f.exists() )
660+
{
661+
basePath = Shared.i().getIncludeDirectory();
662+
f = new File( basePath + filename );
663+
}
664+
665+
if( f.exists() )
666+
{
667+
Document xmlDoc = Shared.loadXmlDocument( f.getPath() );
668+
XPathFactory xpathFactory = XPathFactory.newInstance();
669+
XPath xpath = xpathFactory.newXPath();
670+
671+
try
672+
{
673+
String name = (String) xpath.evaluate("//name", xmlDoc, XPathConstants.STRING);
674+
// get anchor from original filename
675+
String path = f.getAbsolutePath();
676+
String anchorBase = path.substring( path.lastIndexOf("/")+1, path.indexOf(".xml"));
677+
if( name.endsWith("()") )
678+
{
679+
if( !anchorBase.endsWith("_" ) )
680+
{
681+
anchorBase += "_";
682+
}
683+
}
684+
String anchor = anchorBase + ".html";
685+
686+
// get method name from xml
687+
// get anchor from method name
688+
HashMap<String, String> map = new HashMap<String, String>();
689+
map.put( "name", name );
690+
map.put( "anchor", anchor );
691+
vars.add( map );
692+
} catch (XPathExpressionException e)
693+
{
694+
e.printStackTrace();
695+
}
696+
697+
}
698+
699+
}
700+
648701
return templateWriter.writeLoop("related.partial.html", vars);
649702
}
650703

‎java_generate/ReferenceGenerator/src/writers/Shared.java‎

Lines changed: 55 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,24 @@
11
package writers;
22

33
import java.io.File;
4+
import java.io.IOException;
45
import java.util.ArrayList;
56

7+
import javax.xml.parsers.DocumentBuilder;
8+
import javax.xml.parsers.DocumentBuilderFactory;
9+
import javax.xml.parsers.ParserConfigurationException;
10+
11+
import org.w3c.dom.Document;
12+
import org.xml.sax.SAXException;
13+
614
import com.sun.javadoc.Doc;
715
import com.sun.javadoc.ProgramElementDoc;
816

917
public class Shared {
1018
// what we're looking for
1119
private static Shared instance;
1220
private String webrefTagName = "webref";
21+
private String seeAlsoTagName = "see_external";
1322
private String coreClassName = "PApplet";
1423
private ArrayList<String> descriptionSets;
1524

@@ -22,6 +31,8 @@ public class Shared {
2231
//where things come from
2332
private String templateDirectory = "templates";
2433
private String exampleDirectory = "web_examples";
34+
private String includeDirectory = "include";
35+
2536
boolean noisy = false;
2637
public ArrayList<String> corePackages;
2738
public ArrayList<String> rootClasses;
@@ -47,13 +58,31 @@ public String getWebrefTagName(){
4758
return webrefTagName;
4859
}
4960

50-
public void setWebrefTagName(String webrefTagName) {
61+
public String getSeeAlsoTagName()
62+
{
63+
return seeAlsoTagName;
64+
}
65+
66+
public void setIncludeDirectory( String s )
67+
{
68+
includeDirectory = s;
69+
}
70+
71+
public String getIncludeDirectory()
72+
{
73+
return includeDirectory + "/";
74+
}
75+
76+
public void setWebrefTagName(String webrefTagName)
77+
{
5178
this.webrefTagName = webrefTagName;
5279
}
53-
public void setCoreClassName(String coreClassName) {
80+
public void setCoreClassName(String coreClassName)
81+
{
5482
this.coreClassName = coreClassName;
5583
}
56-
public String getCoreClassName() {
84+
public String getCoreClassName()
85+
{
5786
return coreClassName;
5887
}
5988

@@ -152,6 +181,29 @@ public void createOutputDirectory(String dir){
152181
f.mkdirs();
153182
}
154183

184+
public static Document loadXmlDocument( String path )
185+
{
186+
DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();
187+
factory.setNamespaceAware(true);
188+
DocumentBuilder builder;
189+
Document doc = null;
190+
try {
191+
builder = factory.newDocumentBuilder();
192+
doc = builder.parse( path );
193+
} catch (ParserConfigurationException e) {
194+
System.out.println("Failed to parse " + path );
195+
System.out.println( e.getLocalizedMessage() );
196+
} catch (SAXException e) {
197+
System.out.println("Failed to parse " + path );
198+
System.out.println( e.getLocalizedMessage() );
199+
} catch (IOException e) {
200+
System.out.println("Failed to parse " + path );
201+
System.out.println( e.getLocalizedMessage() );
202+
}
203+
204+
return doc;
205+
}
206+
155207
public void createBaseDirectories(){
156208
File f = new File(getLocalOutputDirectory());
157209
f.mkdirs();

0 commit comments

Comments
 (0)