Added some comments to help understand the reference generation steps better

fjenett · fjenett · commit 832bd80ab068 · 2012-12-09T11:17:42.000Z
diff --git a/java_generate/ReferenceGenerator/src/ProcessingWeblet.java b/java_generate/ReferenceGenerator/src/ProcessingWeblet.java
@@ -41,32 +41,44 @@ public class ProcessingWeblet extends Standard {
 	private static String xmlDescriptionFlag = "-includeXMLTag";
 	private static IndexWriter indexWriter;
 
-	public static boolean start(RootDoc root) {
+	public static boolean start(RootDoc root) 
+	{
 		setConfig(root.options());
 		Shared.i().createBaseDirectories();
-		
+
 		indexWriter = new IndexWriter();
 		
-		try {			
+		try 
+		{
+			// write out everything in the .java files:
+			// Classes, Methods, Fields ... see specific XxxWriters
+
 			System.out.println("\n===Writing .javadoc sourced reference.===");
-			// write out everything in the .java files
+
 			writeContents(root);
 			
+			// write out everything in the include directory:
+			// see: /api_en/include
+
 			System.out.println("===Source code @webref files written.===");
 			
 			if (!Shared.i().getIncludeDirectory().equals(""))
-			{   // need to get something back from
-				// this to create index
+			{
 				System.out.println("\n===Writing XML-sourced reference.===");
 				XMLReferenceWriter.write( Shared.i().getIncludeDirectory(), indexWriter);
 				System.out.println("===Include directory files written.===");
 			}
+
+			// write out the index file
+
 			System.out.println("\n===Telling the index to write itself.===");
 			indexWriter.write();
+
 		} catch (IOException e) {
 			// TODO Auto-generated catch block
 			e.printStackTrace();
 		}
+		
 		System.out.println("===All finished in the weblet.===");
 		return true;
 	}
diff --git a/java_generate/ReferenceGenerator/src/writers/BaseWriter.java b/java_generate/ReferenceGenerator/src/writers/BaseWriter.java
@@ -365,21 +365,30 @@ protected static String getXMLDescription(ProgramElementDoc doc) throws IOExcept
 		}
 	}
 	
-	protected static String getXMLDescription(Document doc) {
+	/**
+	 *	Based upon Shared.addDescriptionTag().
+	 *
+	 *	Hint: this loads and adds js_mode/description as well
+	 */
+	protected static String getXMLDescription(Document doc) 
+	{
 		XPathFactory xpathFactory = XPathFactory.newInstance();
 		XPath xpath = xpathFactory.newXPath();
 		
 		String desc = "";
 		
 		for( String component : Shared.i().getDescriptionSets() )
 		{
-			try{
+			try
+			{
 				XPathExpression expr = xpath.compile(component);
 				String result = (String) expr.evaluate(doc, XPathConstants.STRING);
 				if ( !desc.equals("") )
 					desc += "<br /><br />\n";
 				desc += result;
-			} catch ( XPathExpressionException e){
+			} 
+			catch ( XPathExpressionException e)
+			{
 				System.out.println("Error getting description from xml with expression: //" + component);
 				e.printStackTrace();
 			}
