Package Torello.HTML.Tools.JavaDoc

This package utilizes the value of an HTML Parser and Search Engine for allowing a user to transform, modify, add-to, and delete HTML nodes (automatically) into an HTML page. The package JavaDoc does this for programmers who would like to do things like automatically add code-hilited code-snippets, for example, directly onto their professionally written Java-Doc Comment-HTML Pages.

There is a Java-Parser Library that is required to use this Package. The Java Doc Upgrader Package / Tool will not work without this '.jar' file being placed in your CLASSPATH environment-variable. That '.jar' is available here:

http://developer.torello.directory/ralphsReference/jars/javaparser-core-3.16.2.jar


EXAMPLE: Below is an example use of the HTML 'class=' tags defined above. This "EXAMPLE" uses the class='EXAMPLE' tag, in fact. Make sure to scroll to the bottom to see the entire definition. 


 /**
  * Creates a {@code TagNode}, an inherited class of {@code 'HTMLNode'} that can be used as an 
  * element of an HTML {@code Vector}.
  *
  * <BR /><BR /><B>NOTE:</B> Attribute values are neither parsed, nor checked when this
  * constructor is used.  This constructor could allow malformed HTML to be passed to the
  * {@code public final String str} field!
  * 
  * <DIV CLASS="EXAMPLE">{@code
  * TagNode tn = new TagNode("<DIV CLASS='SUMMARY' onmouseover=\"alert('Hello!');\">");
  * System.out.println(tn.str);
  * 
  * // Prints to Terminal: <DIV CLASS='SUMMARY' onmouseover="alert('Hello!');">
  * }</DIV>
  *
  * @param s Any valid HTML tag, for instance: {@code <H1>, <A HREF="somoe url">,
  * <DIV ID="some id">} etc...
  * 
  * @throws MalformedTagNodeException If the passed {@code String} wasn't valid - meaning <I>it
  * did not match the regular-expression {@code parser}.</I> 
  * 
  * @throws HTMLTokException If the {@code String} found where the usual HTML token-element is
  * situated <I>is not a valid HTML element</I> then the {@code HTMLTokException} will be
  * thrown.
  * 
  * @see HTMLTags#getTag_MEM_HEAP_CHECKOUT_COPY(String)
  */
 public TagNode(String s)
 {
     super(s);

     // If the second character of the string is a forward-slash, this must be a closing-element
     // For Example: </SPAN>, </DIV>, </A>, etc...

     isClosing = s.charAt(1) == '/';

     // This is the Element & Attribute Matcher used by the RegEx Parser.  If this Matcher doesn't
     // find a match, the parameter 's' cannot be a valid HTML Element.  NOTE: The results of this
     // matcher are also used to retrieve attribute-values, but here below, its results are ignored.

     Matcher m = HTMLRegEx.P1.matcher(s);
     ...
 }




OUTPUT TO JAVADOC: The code above demonstrates how to include HTML divider elements into your Java-Doc Code Segments. These divider class attributes are listed in the next table. Sample code-snippets are hilited and then inserted into your class source-files, as per example above. The original JavaDoc program generated HTML files will are updated, not replaced.

Example



The classes inside this package may be later added to and extended. The core functionality is quite stable, but more work would help make adding certain concepts to a Java-Doc Generated HTML Page easier.

PRIMARY USE: The following table will present a list of options that are available for adding Hilited Code-Snippets to Java-Documentation HTML Files. The means by which a programmer can insert code snippets into the JavaDoc Code-Documentation Part of a Java Source File is as follows:

HTML-DIV Class-NameRationale
COMPLETE The HTML <DIV> element contains the complete method body of your java method. codeParameter 'java' will be sent to HiLite.Me server to hilite the code in this code-documentation portion.
EXAMPLE The <DIV> element contains java-code that serves as an example in your documentation. codeParameter 'java' will be sent to HiLite.Me server to hilite the code in this code-documentation portion.
METHODSIGNATURE The <DIV> element you have provided java-doc is the signature of one of your java methods, but doesn't include the method body. codeParameter 'java' will be sent to HiLite.Me server to hilite the code in this code-documentation portion.
SNIP The <DIV> element is expected to contain a "sub-section" of java-code, not a complete method body. codeParameter 'java' will be sent to the server to hilite the code in this code-documentation portion.
HTML This <DIV> element contains HTML code, and is intended to be seen as "escaped HTML" rather than "rendered HTML." codeParameter 'HTML' will be sent to the server when this code is hilited.
JAVASCRIPT The <DIV> element contains "java-script" code. It should be viewed as hilited java-script. codeParameter 'js' will be used with the server. It may be an entire function definition, or merely a few lines, all are considered OK when using this class-name with a <DIV> in your documentation.
LOC The <DIV> element will contain a single line of Java-Code. codeParameter 'java' will be used with the server.
SHELL The <DIV> element will contain a single line of UNIX or MS-DOS shell code. The <DIV> contents will not be hilited, and the server will not be queried. Instead, a CSS-Style element will be inserted into the <DIV> that lightens the text, and darkens the background.
SHELLBLOCK The <DIV> element will contain multiple lines of UNIX or MS-DOS shell code. The <DIV> contents will not be hilited, and the server will not be queried. Instead, a CSS-Style element will be inserted into the <DIV> that lightens the text, and darkens the background.
REGEX The <DIV> element will contain Regular-Expression Data. It will be hilited. The <DIV> contents will not be hilited by the server - which will not be queried. Instead, a CSS-Style element will be inserted into the <DIV> that lightens the text, and darkens the background.
JSON The <DIV> element will contain JSON Data
CSS The <DIV> element will contain CSS Data
XML The <DIV> element will contain XML Data
SQL The <DIV> element will contain SQL Data



Java Parser Bridge Classes

This section of the package is capable of parsing a java-source file, and returning the parse results as a series of String's. This package utilizes a suite of classes developed for the Java Developers called Java-Parser. It may be freely read about by doing the most basic Google Search. After parsing a '.java' source-code file, the results that are returned will be included in an instance of class SourceFile. This class functions as BOTH the source-file parser, AND the results container class. Contained within an instance of class SourceFile - which one may obtain when invoking that class' public SourceFile.parse(String) and parseFile(String) methods - are a series of Vector's that contain instances of the following classes:

  • class Method - which has a number of 'String' fields holding information about any and all methods that are declared in the Source-File that has been passed to the 'parse()' or 'parseFile()' methods.

  • class Constructor - which also has 'String' fields that hold information about any constructors that are discovered and retrieved.

  • class Field - Same as above, contains information saved as String's about any fields that are identified by the JavaParser Package inside your source file.