Package Torello.HTML.Tools.JavaDoc
Class Upgrade
- java.lang.Object
-
- Torello.HTML.Tools.JavaDoc.Upgrade
-
public class Upgrade extends java.lang.Object
JavaDoc Upgrade (Builder) - Documentation.
This is the class that 'Upgrades' the standard Java Doc'.html'
pages into the form that you are reading right now.
IMPORTANT NOTE: Before any of the features of this Upgrader Tool will function, an outside JAR-library distribution must be included in the JavaCLASSPATH
environment variable. The link below is a link to theJava Parser JAR
. There is a book available about this library, and an internet Gitter.com Support Page (chat-room) hosted by some of the people involved in writing this JAR library. The completeJava Parser Library
has many Java'.jar'
files associated, but only the core-library is needed for running the tasks in this Upgrade Tool.
This'.jar'
file may be donloaded here:
http://developer.torello.directory/ralphsReference/jars/javaparser-core-3.16.2.jar
What follows is an example where some of the initializer fields for this upgrader are actually used. Note that this class has a command-linemain(String[])
method available. Recognize that the CLI version of this class does not initialize any of the fields (except possibly theHiLiter Cache
), and that this upgrader tool can be run without anything complicated if need be.
Example:1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18
// The location where JDK's "javadoc" has sent its output public static final String LOCAL_JAVADOC_DIR = "javadoc/"; // A simple two-column text-file which maps FILE-ID's to file-names. // The files, themselves, should contain HTML for auto-insert into your documentation. public static final String HILITE_EMBEDID_MAP_FILE = "Torello/Build/TXT/ids.txt"; // Text-file which lists classes, interfaces, etc... whose fields should NOT be syntax-hilited. public static final String LEAVEOUT_FIELDS_LIST_FNAME = "Torello/Build/TXT/SkipAllFields.txt"; // Text-file which lists classes, interfaces, etc... whose source-code file should NOT be hilited. public static final String LEAVEOUT_SRCFILES_LIST_FNAME = "Torello/Build/TXT/SkipSrcFile.txt"; public static final StrFilter HILITE_ALL_FIELDS_PRED = StrFilter.strListREJECT_NOIOE(LEAVEOUT_FIELDS_LIST_FNAME, false); public static final StrFilter HILITE_SRC_FILE_PRED = StrFilter.strListREJECT_NOIOE(LEAVEOUT_SRCFILES_LIST_FNAME, false);
The above constants are passed as parameters to theUpgrade
Tool's initialization "hamburger stack". The last method invoked on this stack is therun()
method.
Example:1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23
// Saves text internally, prints to the log-file, and prints to terminal. StorageWriter sw = new StorageWriter(); // These four lines allow the Upgrade Tool to cache results for documentation web-pages // as they are hilited so that future builds will not have to "re-poll" the server when // hiliting source-code files that have not changed. Use as depicted below. String HILITEME_CACHE = "cache/"; // directory name File f = new File(HILITEME_CACHE); if (! f.exists()) { f.mkdirs(); HiLiteMe.Cache.initializeOrClear(HILITEME_CACHE, sw); } HiLiteMe.Cache CACHE = new HiLiteMe.Cache(HILITEME_CACHE); new Upgrade (LOCAL_JAVADOC_DIR, "") .setLogFile ("log.html") .setFaviconFileFormat (Torello.HTML.Tools.Images.IF.JPG) .setEmbedTagsMapFile (HILITE_EMBEDID_MAP_FILE) .setHiLiteAllFieldsFilter (HILITE_ALL_FIELDS_PRED) .setHiLiteSourceCodeFileFilter (HILITE_SRC_FILE_PRED) .useHiLiteServerCache (CACHE) .useDefaultPackageSummaryCleaner () .upgrade(sw);
Hi-Lited Source-Code:
- View Here: Torello/HTML/Tools/JavaDoc/Upgrade.java
- Open New Browser-Tab: Torello/HTML/Tools/JavaDoc/Upgrade.java
-
-
Field Summary
Fields Modifier and Type Field protected boolean
checkBalance
protected Predicate<String>
cssTagsFilter
protected Hashtable<String,
String>embedTagIDTable
protected Consumer<CommonParamRecord>
extraTasks
static String
FAVICON_FILE_NAME
protected String
faviconImageFileName
protected Predicate<String>
hiLiteAllConstructorsFilter
protected Predicate<String>
hiLiteAllFieldsFilter
protected Predicate<String>
hiLiteAllMethodsFilter
protected HiLiter
hiLiter
protected Predicate<String>
hiLiteSourceCodeFileFilter
static String
JAVA_DOC_CSS_FILE_NAME
protected String
jdCSS
protected Consumer<String>
logFile
protected Consumer<Vector<HTMLNode>>
packageSummaryCleaner
protected boolean
printStats
protected RearrangePkgFrame.PackageItems
rearrangeFrames
protected String
rootJavaDocDirectory
protected String
rootSourceFileDirectory
protected Stats
stats
protected RearrangeSummaries.SummaryItems
summaryItems
protected Predicate<String>
summaryRemoveFilter
protected boolean
VERBOSE_PRINT_STEPS
-
Constructor Summary
Constructors Constructor Upgrade(String rootJavaDocDirectory, String rootSourceFileDirectory)
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Upgrade
doNotAddCSSTags()
Upgrade
doNotHiLiteFields()
Upgrade
doNotHiLiteMethods()
Upgrade
doNotHiLiteSourceCodeFiles()
Upgrade
doNotRemoveSummaries()
Upgrade
hiLiteConstructors()
static void
main(String[] argv)
Upgrade
printStats(boolean print)
static String
retrieveDefaultJDCSSFileFromJAR()
void
run(String jdFileName, StorageWriter sw)
Upgrade
setCheckBalance(boolean checkBalance)
Upgrade
setCSSTagsFilter(Predicate<? super String> cietNameFilter)
Upgrade
setCustomJDCSSFile(String CSSFileAsAString)
Upgrade
setEmbedTagsMap(Map<String,String> tagIDMap)
Upgrade
setEmbedTagsMapFile(String tagIDMapFileName)
Upgrade
setExtraTasks(Consumer<CommonParamRecord> extraTasks)
Upgrade
setFaviconFileFormat(IF faviconFileFormat)
Upgrade
setHiLiteAllConstructorsFilter(Predicate<? super String> cietNameFilter)
Upgrade
setHiLiteAllFieldsFilter(Predicate<? super String> cietNameFilter)
Upgrade
setHiLiteAllMethodsFilter(Predicate<? super String> cietNameFilter)
Upgrade
setHiLiter(HiLiter hiLiter)
Upgrade
setHiLiteSourceCodeFileFilter(Predicate<? super String> cietNameFilter)
Upgrade
setLogFile(String logFileName)
Upgrade
setLogFile(Consumer<String> consumerLogFile)
Upgrade
setPackageFrames(String[] packages, String[][] sectionNames, String[][][] sectionContents, boolean usesFrames)
Upgrade
setPackageSummaryCleaner(Consumer<Vector<HTMLNode>> packageSummaryCleaner)
Upgrade
setSummaryRearrange(String[] ciets, String[][] sectionNames, FCM[] sections, java.util.function.ToIntFunction[] sorters)
Upgrade
setSummaryRemoveFilter(Predicate<? super String> cietNameFilter)
Upgrade
turnOffVerboseProcessPrint()
Stats
upgrade(StorageWriter sw)
Upgrade
useDefaultPackageSummaryCleaner()
Upgrade
useHiLiteServerCache(HiLiteMe.Cache cache)
-
-
-
Field Detail
-
JAVA_DOC_CSS_FILE_NAME
public static final java.lang.String JAVA_DOC_CSS_FILE_NAME
The name of the JavaDoc CSS Definitions file. This filename may not be changed.- See Also:
- Constant Field Values
- Code:
- Exact Field Declaration Expression:
1
public static final String JAVA_DOC_CSS_FILE_NAME = "JavaDoc.css";
-
FAVICON_FILE_NAME
public static final java.lang.String FAVICON_FILE_NAME
The name of the favicon-file (without extension). This filename may not be changed.- See Also:
- Constant Field Values
- Code:
- Exact Field Declaration Expression:
1
public static final String FAVICON_FILE_NAME = "favicon";
-
rootJavaDocDirectory
protected final java.lang.String rootJavaDocDirectory
The Root Java Doc output directory. This is usually just'javadoc/'
- Code:
- Exact Field Declaration Expression:
1
protected final String rootJavaDocDirectory;
-
rootSourceFileDirectory
protected final java.lang.String rootSourceFileDirectory
The Root Source-Code directory- Code:
- Exact Field Declaration Expression:
1
protected final String rootSourceFileDirectory;
-
faviconImageFileName
protected java.lang.String faviconImageFileName
This helps add a favicon to JavaDoc Pages. When thisString
is set to a non-null value, an HTML Favicon Link will be inserted into each web-page of the code documentation. A favicon is a small graphical image that appears in the top corner of the web-page tabs when viewing a web-page.
In order to set this field, an image-type file-extension needs to be provided. When the image file-extension is provided, an HTML'<link rel='icon' type='image/jpg' href='../favicon.jpg' />'
element will be inserted into each page of the Java-Doc Upgraded Pages.
ALSO: To maintain simplicity of the tool, the favicon file-name"favicon"
cannot be changed. However, the extenion may be set to any of the file extensions provided in class IF - including'.jpg', '.png'
, etc...
When the image-type file-extension is set, an HTML'<link rel='icon' type='image/jpg' href='../favicon.jpg' />'
element will be inserted into each page of the Java-Doc Upgraded Pages. The specific../..' String
is auto-computed for each page.
FINALLY: When afavicon
link is requested, the actual image file must manually be copied into the java-doc root directory - or the browser will not find the favicon! After running the Java-Doc on your'.html'
files, simply copy the'favicon.EXT'
image file to the root output Java Doc directory, and the browser will be able to find the image, using the'<LINK>'
element's which this tool will have inserted.- See Also:
setFaviconFileFormat(IF)
,IF
- Code:
- Exact Field Declaration Expression:
1
protected String faviconImageFileName = null;
-
VERBOSE_PRINT_STEPS
protected boolean VERBOSE_PRINT_STEPS
The steps that the Java-Doc Upgrader Tools is taking are printed to the providedStorageWriter
when this field is set to 'TRUE'.
NOTE: If no instance ofStorageWriter
is passed to the Upgrader's primary'run(...)'
method, then process-step output will not be displayed - regardless of the value of this'boolean'
field.- Code:
- Exact Field Declaration Expression:
1
protected boolean VERBOSE_PRINT_STEPS = true;
-
logFile
protected java.util.function.Consumer<java.lang.String> logFile
Output log information is only sent to the passed instance ofStorageWriter
, but if alogFile
(or anyString-Consumer
) is provided, this information can be check-pointed to the file-system to prevent large JavaStringBuilder
instances with hundreds or thousands of log-fileString's
from slowing down the memory-model or garbage collector.- See Also:
setLogFile(java.util.function.Consumer<java.lang.String>)
,setLogFile(java.lang.String)
- Code:
- Exact Field Declaration Expression:
1
protected Consumer<String> logFile = null;
-
embedTagIDTable
protected final java.util.Hashtable<java.lang.String,java.lang.String> embedTagIDTable
This stores the a map of TagID fields to their respective HTML-File File-Names on the file-system. It is used in combination with JavaDoc Source-Code HTML Tags that request "External-HTML" be inserted into a JavaDoc HTML Web-Page.
This Upgrader feature allows programmers to write more detailed code documentation (comments) for their Java Classes while reducing the 'clutter' in the code. If a particular method or field needs a lot of commenting, simply type up an external'.html'
file (leave off the HTML<HEADER>, <BODY>
tags) Then, in your'java'
Source-Code File, insert an HTML<EMBED>
tag - and the Upgrader will automatically insert all of the HTML in the external-documentation file you have created.
The'EMBED'
tag needs to look like:<EMBED CLASS="external-html" DATA-FILE-ID="SOME_ID">
You have the ability to insert these tags into the comments of your source-files, because this Upgrader will replace those HTML elements with the HTML found in the file named by this map. See the image below as an example: Notice that all that has to be provided to the tag is a'DATA-FIILE-ID'
attribute. This'ID'
is mapped to a file-systemtext-file
using this map.
The'embedTagIDTable'
is a really simple 'Map' that translates an'<EMBED>'
element'sDATA-FILE-ID
to an'.html'
file-name (that you have written) on the file-system. TheEmbed Tags Map File
used by thisLibrary's Build Script
may be viewed below, as an example. This is an exhaustive list of all Externally-Linked HTML Pages for theJava HTML
library.
Embed Tags Map File- See Also:
setEmbedTagsMapFile(String)
,setEmbedTagsMap(Map)
- Code:
- Exact Field Declaration Expression:
1
protected final Hashtable<String, String> embedTagIDTable = new Hashtable<>();
-
hiLiter
protected HiLiter hiLiter
The CodeHiLiter
instance. The defaultHiLiter
is used, unlesssetHiLiter
is called.- See Also:
useHiLiteServerCache(HiLiteMe.Cache)
,setHiLiter(HiLiter)
- Code:
- Exact Field Declaration Expression:
1
protected HiLiter hiLiter = HiLiter.getDefault(null, "vim", "native");
-
jdCSS
protected java.lang.String jdCSS
This should be the contents of the intendedCSS Rules
written to the file'JavaDoc.css'
which shall live in the root-directory of the javadoc file-tree. A link to this CSS file is inserted into each and every java-doc page that is updated.
NOTE: ThisCSS File
is only useable if the user has not invokeddoNotAddCSSTags()
. If the Upgrader is prohibited from addingCSS Tags
to Java-Doc generated web-pages, then theCSS Rules
will be not be useable by the browser.
NOTE: The defaultCSS Rules
for the CSSCLASS
andID
tags created will be the same ones that are used in this documentation page that you are looking at right now. The default CSS may be changed by assigning a specialized CSS page using the'setCustomJDCSSFile(String)'
method in this class.
The defaultCSS File
may be viewed here:
Default CSS File- See Also:
setCustomJDCSSFile(String)
,doNotAddCSSTags()
- Code:
- Exact Field Declaration Expression:
1
protected String jdCSS = null;
-
packageSummaryCleaner
protected java.util.function.Consumer<java.util.Vector<HTMLNode>> packageSummaryCleaner
Very often, when building the pagespackage-summary.html
for a particular JavaDoc package, theclasses
andinterfaces
that are inserted into the page will look horribly skewed - if the comment section of the classes contained any detailed HTML segments. Setting a Package Summary Cleaner will remove most of the text inserted into that page. The default cleaner is:
CleanPackageSummaries.defaultCleaner(Vector)
- See Also:
setPackageSummaryCleaner(Consumer)
,useDefaultPackageSummaryCleaner()
,CleanPackageSummaries.defaultCleaner(java.util.Vector<Torello.HTML.HTMLNode>)
- Code:
- Exact Field Declaration Expression:
1
protected Consumer<Vector<HTMLNode>> packageSummaryCleaner = null;
-
extraTasks
protected java.util.function.Consumer<CommonParamRecord> extraTasks
This instance ofConsumer<CommonParamRecod>
should be registered by the user. This allows a user to modify the HTML of a JavaDoc HTML Web-Page in whatever proprietary or custom manner that you would like. A programmer might wish to add HTML<META>
tags to the header, or perhaps add some recurring-automated comments to each method description.
Thisjava.util.function.Consumer<CommonParamRecord>
will receive the same record-instance that is passed to all of the main-operation classes in this library. The most important part to remember is that any modifications to the JavaDoc Web-Page need to be performed on the'fileVec'
parameter.
NOTE: Modifying HTML is niether difficult, nor tedious, but it does require knowledge of the classes, interfaces, etc. in both theTorello.HTML
and theNodeSearch
packages. In any case, just about everything you would need to know about a Java Doc HTML page is provided in the parameters of theCommonParamRecord
class.- See Also:
setExtraTasks(Consumer)
- Code:
- Exact Field Declaration Expression:
1
protected Consumer<CommonParamRecord> extraTasks = null;
-
rearrangeFrames
protected RearrangePkgFrame.PackageItems rearrangeFrames
This field may be set if you would like to create upgradedPackage Frames.
It is not important to know how theRearrangePkgFrame
class works, but click the link to this internally-used class to read about it.
The purpose of this is to allow the user to easily change the layout of the'package-frame.html'
page in Java Doc. Later versions of the Java Doc Tool give warning messages that 'Frames' are going to be deprecated. I personally don't really understand why because they add tremendously to the look-and-feel of the page.
IMPORTANT: Setting this field will also result in thepackage-summary.html
files being re-arranged according to the specified input arrays. Remember that providing a more logical arrangement of the class, interfaces, exceptions, etc... for your JAR Library files can make reading them and browsing them orders of magnitude more lucid and well-thought out.
Below is a link to example input arrays, and how they should look. The arrays in the link are actually the exact onese used to rearrange thepackage-frame.html
files employed by thisJava HTML
library.Torello.Build.Helper.PackageItems.java
The changes that can be made are explained more clearly with a simple picture:
The changes made to thepackage-summary.html
HTML Files can be seen here:- See Also:
setPackageFrames(String[], String[][], String[][][], boolean)
- Code:
- Exact Field Declaration Expression:
1
protected RearrangePkgFrame.PackageItems rearrangeFrames = null;
-
summaryItems
protected RearrangeSummaries.SummaryItems summaryItems
This is the field that is used to re-arrange "Summary Sections" inside a Java-Doc HTML Page. The "Summary Sections" are a "Table of Contents" for methods, fields, constructors etc... at the top of a Java-Doc Generated Documentation Page. The default version of the "Field Summaries" section, for example, will list the fields inside of a class, but the list itself cannot be partitioned in categories or sub-lists - which can make for more difficult reading. The class RearrangeSummaries allows you to create 'sections' inside this 'Table of Contents' with category-names, and a sorter algorithm of your choosing. This can effectively make much nicer-looking summaries in your documentation pages.
Below is a sample of what the arrays should look like in order for this upgrader to perform such an upgrade. This is the "Rearrange Summaries" list of arrays used to build the Java HTML Library. This file is quite long, but reading might make it easier to understand what actually belongs inside these arrays. At the very end of the class in this link, the arrays are collated so that they may be passed to: setSummaryRearrange(...)
Torello.Build.Helper.SummRearrange.java
For a more visual explanation of what the'Summary Items'
are, please review the following before and after screen clips:- See Also:
setSummaryRearrange(String[], String[][], FCM[], ToIntFunction[])
- Code:
- Exact Field Declaration Expression:
1
protected RearrangeSummaries.SummaryItems summaryItems = null;
-
checkBalance
protected boolean checkBalance
This flagboolean
is, by default, set toTRUE
. ThisUpgrade
tool uses the class Torello.HTML.Balance to check for validity inside of all HTML files it encounters - including both the externally linked Embed-Tag HTML files, and the JavaDoc generated HTML files. The type of 'validity' that is checked is for unclosed HTML-tags.
There is more explanation of what consitutes a "Balanced HTML File" inclass Balance
. To summarize the information there, all that the code really does is to check (for all non-singleton tags, only), that there are an equal number of opening and closing versions of each HTML element. For example, the balance-checker counts the number of'<DIV>'
elements and the number of'</DIV>'
elements, and if there are not an equal number of them, an exception is thrown. (No more, no less)
NOTE: Singleton tags (such as<IMG ...>
) are not checked because they are not expected to be closed, they are stand-alone tags. The code, here, will also pass on checking attribute-validity. An HTML<IMG>
that (accidentally) uses anHREF=...
instead of aSRC=...
, though erroneous, is an error that is not caught by this checker. Future versions of this tool may work on this problem.
FINALLY: JavaDoc generates valid HTML, but a programmer who inserts HTML into his comments may encounter situations where this check helps debugging the documentation. There are boundary cases involing the tag'<LI>'
, as some web-designers feel that it is not necessary to close these tags with a'</LI>'
, however this checker will not allow this. To allow for unclosed, non-singleton tags, this checker must be turned off.- See Also:
setCheckBalance(boolean)
- Code:
- Exact Field Declaration Expression:
1
protected boolean checkBalance = true;
-
stats
protected final Stats stats
Keeps some statistics about the upgrade / build. View / use after upgrader completes.- Code:
- Exact Field Declaration Expression:
1
protected final Stats stats = new Stats();
-
printStats
protected boolean printStats
Requests whether to print the statistics to the output.- Code:
- Exact Field Declaration Expression:
1
protected boolean printStats = true;
-
summaryRemoveFilter
protected java.util.function.Predicate<java.lang.String> summaryRemoveFilter
This filter is used to decide whichclass, interface, enum
etc...'.java'
Source-Code Files need to avoid having their 'Summary Descriptions' removed. The Java Doc Tool inserts summaries into aMethod Summaries
,Field Summaries
, andConstructor Summaries
, section at the top of a Java Doc page. They are at the top of the Java Doc'.html'
file.
NOTE: The default initialization value of'null'
for the'summaryRemoveFilter'
field implies you want this Upgrade Tool to remove the summary text for all Java-Doc'.html'
Pages.
Generally, the English-Language (or any written, human language) HTML description in a Java Doc Comment looks reasonably nice in the details portion of Java-Doc Page. However, in the summaries portion, for just about anything but the most trivial of comments, the JavaDoc Logic (which just abbreviates the comments) rarely produces a nice enough looking'Summary Description'
to be useable. The'AI'
just isn't advanced enough to automatically figure out what you want the summary to say. Therefore, the signature, by itself, ought be enough.
This default behavior may be changed by selecting and identifyingclasses, intefaces,
etc., which you would like to see retain their abbreviated description summaries.
Cleaned Summaries look as in the picture below:- See Also:
setSummaryRemoveFilter(Predicate)
,doNotRemoveSummaries()
- Code:
- Exact Field Declaration Expression:
1
protected Predicate<String> summaryRemoveFilter = null;
-
hiLiteSourceCodeFileFilter
protected java.util.function.Predicate<java.lang.String> hiLiteSourceCodeFileFilter
This filter is used to decide which Class, Interface or Enumerated-Type'.java'
Source-Code Files will be hilited, and have links to an'.html'
file included in their respective Java-Doc'.html'
page. The default initialization value of'null'
will result in *all* Java-Doc Pages having a code-hilited HTML Anchor'<A HREF=...>'
link inserted into their respective Java-Doc pages. This anchor will link the page to a HiLited-version of the Source-Code'.java'
file from which the Java-Doc HTML Page was generated.
TheDo Not HiLite Source-Code Files Filter
for thisJar Distribution Package
can be viewed here, below (as an example). TheClasses
listed in this file are all the classes for which no'Source Code'
File HiLiting is performed. If you view the Documentation Pages for the classes listed in this file, you will see the automatically-added "Source Code" links are actually manually added by a different portion of the build script.
The content of this file are loaded into aStrFilter
, and passed tosetHiLiteSourceCodeFileFilter(Predicate)
Skip All Source-File HiLiting Text File
The above file is loaded into thisPredicate<String>
by calling:
StrFilter.strListREJECT_NOIOE(String, boolean)
TheHiLited Source Code File
procedure is the one which creates links on your Java Doc Pages that look like:- See Also:
setHiLiteSourceCodeFileFilter(Predicate)
,doNotHiLiteSourceCodeFiles()
- Code:
- Exact Field Declaration Expression:
1
protected Predicate<String> hiLiteSourceCodeFileFilter = null;
-
hiLiteAllMethodsFilter
protected java.util.function.Predicate<java.lang.String> hiLiteAllMethodsFilter
This filter is used to decide which Class, Interface or Enumerated-Type'.html'
Java-Doc Files will have their method bodies hilited and inserted in their respective JavaDoc'.html'
pages. The default initialization value of'null'
will result in *all* Java-Doc Pages having code-hilited method-bodies inserted into their Java-Doc Pages.
TheDo Not HiLite Methods Filter
for thisJar Distribution Package
can be viewed here, below (as an example). TheClasses
listed in this file are all the classes for which no'Method Body'
HiLiting is performed. The file is loaded into aStrFilter
, and passed tosetHiLiteAllMethodsFilter(Predicate)
Skip All Methods HiLiting Text File
The above file is loaded into thisPredicate<String>
by calling:
StrFilter.strListREJECT_NOIOE(String, boolean)
TheHiLite Method Body
procedure is the one which creates segments on your Java Doc Pages that look like:- See Also:
setHiLiteAllMethodsFilter(Predicate)
,doNotHiLiteMethods()
- Code:
- Exact Field Declaration Expression:
1
protected Predicate<String> hiLiteAllMethodsFilter = null;
-
hiLiteAllFieldsFilter
protected java.util.function.Predicate<java.lang.String> hiLiteAllFieldsFilter
This filter is used to decided which Class, Interface or Enumerated-Type'.html'
Java-Doc Files will have their field declarations hilited and inserted in their respective JavaDoc'.html'
pages. The default initialization value of'null'
will result in *all* Java-Doc Pages having code-hilited field-declarations inserted into their Java-Doc Pages.
TheDo Not HiLite Fields Filter
for thisJar Distribution Package
can be viewed here, below (as an example). TheClasses
listed in this file are all the classes for which no'Field Declaration'
HiLiting is performed. The file is loaded into aStrFilter
, and passed tosetHiLiteAllFieldsFilter(Predicate)
Skip All Fields HiLiting Text File
The above file is loaded into thisPredicate<String>
by calling:
StrFilter.strListREJECT_NOIOE(String, boolean)
TheHiLite Field Declaration
procedure is the one which creates segments on your Java Doc Pages that look like:- See Also:
setHiLiteAllFieldsFilter(Predicate)
,doNotHiLiteFields()
- Code:
- Exact Field Declaration Expression:
1
protected Predicate<String> hiLiteAllFieldsFilter = null;
-
hiLiteAllConstructorsFilter
protected java.util.function.Predicate<java.lang.String> hiLiteAllConstructorsFilter
This filter is used to decided which Class, Interface or Enumerated-Type'.html'
Java-Doc Files will have their constructor declarations hilited and inserted in their respective JavaDoc'.html'
pages. The default initialization value of'null'
will result in *none* of the Java-Doc Pages having code-hilited constructor-declarations inserted into their Java-Doc Pages.
TheHiLite Constructors Filter
for thisJar Distribution Package
can be viewed here, below (as an example). TheClasses
listed in this file are all the classes for which'Constructor Declaration'
HiLiting is performed. The file is loaded into aStrFilter
, and passed tosetHiLiteAllFieldsFilter(Predicate)
HiLite All Constructors Text File
The above file is loaded into thisPredicate<String>
by calling:
StrFilter.strListKEEP_NOIOE(String, boolean)
TheHiLite Constructor Declaration
procedure is the one which creates segments on your Java Doc Pages that look like:- See Also:
setHiLiteAllConstructorsFilter(Predicate)
,hiLiteConstructors()
- Code:
- Exact Field Declaration Expression:
1
protected Predicate<String> hiLiteAllConstructorsFilter = null;
-
cssTagsFilter
protected java.util.function.Predicate<java.lang.String> cssTagsFilter
This filter is used to decided which Class, Interface or Enumerated-Type'.html'
Java-Doc Files will have CSS-Tags inserted into their respective JavaDoc'.html'
pages. The default initialization value of'null'
will result in *all* Java-Doc Pages having CSS-Tags inserted into the HTML Elements in their respective JavaDoc Pages.
TheInsert CSS Tags
procedure is the one which createsCSS CLASS
attributes in your Java Doc Pages that look:
To see the complete list ofCSS CLASS
attributes that are added to a Java Doc'.html'
File, please reviewclass Colorize
.
The defaultCSS File
may be viewed here:
Default CSS File- See Also:
setCSSTagsFilter(Predicate)
,doNotAddCSSTags()
- Code:
- Exact Field Declaration Expression:
1
protected Predicate<String> cssTagsFilter = null;
-
-
Constructor Detail
-
Upgrade
public Upgrade(java.lang.String rootJavaDocDirectory, java.lang.String rootSourceFileDirectory)
This returns a new instance of this class. It will have all empty and null settings, except the root-directory descriptors. It must be initialized with the various builder methods.
This constructor must tell the Upgrader (Builder) which directory contains'.java'
Source-Files, and which directory shall contain Java-Doc Generated HTML Documentation Pages.- Parameters:
rootJavaDocDirectory
- This is the output directory that was used for the last call to the JavaDoc Utility. The Upgrade Logic should expect to find all class, interface and enumerated types to be hilited in this directory. This parameter may not be null.rootSourceFileDirectory
- This is the location where the'.java'
source files for the classes, interfaces and enumerated types named by your list files. This parameter may not be null.- Throws:
UpgradeException
- This exception will throw if either of these directories cannot be found, or may not be accessed. The'getCause()'
method of the exception will provide more details of the specific error that occurred.- See Also:
rootJavaDocDirectory
,rootSourceFileDirectory
-
-
Method Detail
-
turnOffVerboseProcessPrint
public Upgrade turnOffVerboseProcessPrint()
This turns off the "verbose" process-step printing information to the log'StorageWriter'
output. This usually helps follow along with Java-Doc Upgrader steps. By default, this field is set to 'TRUE.'- See Also:
VERBOSE_PRINT_STEPS
- Code:
- Exact Method Body:
1
VERBOSE_PRINT_STEPS = false; return this;
-
setLogFile
public Upgrade setLogFile (java.util.function.Consumer<java.lang.String> consumerLogFile)
Log information may be sent anywhere. If you need to save Log information somewhere other than a file on the file-system, pass a Java Lambda that accepts Log FileString's
- Parameters:
consumerLogFile
- This may be any lambda which receives log-file writes.- Returns:
- An instance of
'this'
upgrader, for convenience. - See Also:
logFile
- Code:
- Exact Method Body:
1
this.logFile = consumerLogFile; return this;
-
setLogFile
public Upgrade setLogFile(java.lang.String logFileName)
Log information will be sent to the file-name provided, here. This must be an accessible file on the file-system.- Parameters:
logFileName
- This may be any file that is accessible on the (UNIX/DOS) filesystem.- Returns:
- An instance of
'this'
upgrader, for convenience. - Throws:
UpgradeException
- When invoked, this method will attempt to write some preliminary header information to the log-file. If this write fails, anUpgradeException
will be thrown.- See Also:
UpgradeException.checkFileIsWriteable(String, String, String)
,logFile
- Code:
- Exact Method Body:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30
String dateTimeStr = StringParse.dateStr('-') + " " + StringParse.timeStr(':'); String fileHeader = "<HTML>\n<HEAD>\n" + "<TITLE>Log " + dateTimeStr + "</TITLE>\n" + "<STYLE type='text/css'>\n" + Shell.C.getCSSDefinitions() + "\n</STYLE>\n" + "</HEAD>\n" + "<BODY STYLE='margin: 1em; background: black; color: white;'>\n\n" + "<H1>JavaDoc Upgrader Log</H1>\n" + "<CODE>" + dateTimeStr + "</CODE>\n" + "<PRE>\n\n"; // This is just used / passed to the "Exception Checker" (below) to build a more // readable Exception-Message. final String fileDescription = "Disk / File-System Upgrader Log-Dump File"; // Write log-file header. Check that the log-file is accessible and writable. UpgradeException.checkFileIsWriteable(logFileName, fileDescription, fileHeader); // Build a java.util.function.Consumer<String> // This consumer will function as the log-file write-mechanism. logFile = (String s) -> { try { FileRW.appendToFile(s, logFileName); } catch (IOException e) { throw new UpgradeException("Cannot write to log-file: [" + logFileName + "]"); } }; return this;
-
setSummaryRemoveFilter
public Upgrade setSummaryRemoveFilter (java.util.function.Predicate<? super java.lang.String> cietNameFilter)
This filter decides which Java-Doc Web-Pages will have their "Summary Descriptions" removed from the summary tables at the top of a JavaDoc generated web-page. By default this field is null, and when it is - all Java-Doc Pages will have their respective textual, abbreviated "Summary Descriptions" removed from the summary tables which are located at the top of the web-page.
The filter-parameter ('cietNameFilter'
) that needs to be passed here is just a JavaPredicate<String>
. ThisPredicate's 'test(String)'
method will receive the fully-qualified name of a JavaClass, Interface,
orEnum
(CIET) whose source-code documentation-file is being modified.
ThePredicate
should returnTRUE
if you would like to avoid removing theField
andMethod
Summary Text from theField Summaries
andMethod Summaries
for a particular CIET.
NOTE: If you keep a short'.txt'
file that just lists the classes you don't want hilited, you may load that'.txt'
file into a JavaPredicate
using either:
Cleaned Summaries look as in the picture below:- Parameters:
cietNameFilter
- The file-name filter. Thisjava.lang.Predicate<String>
needs to accept or reject the fully qualified name of aClass, Interface,
orEnum
.- See Also:
summaryRemoveFilter
,doNotRemoveSummaries()
,StrFilter
- Code:
- Exact Method Body:
1
this.summaryRemoveFilter = RAW_TYPES_FIX(cietNameFilter); return this;
-
setHiLiteSourceCodeFileFilter
public Upgrade setHiLiteSourceCodeFileFilter (java.util.function.Predicate<? super java.lang.String> cietNameFilter)
This filter decides which Java-Doc Web-Pages will get an HTML Anchor Link'<A HREF=...>'
that contains a local URL with an'.html' file
of the'.java'
Source-Code for the Java-Doc Page being updated. By default this field is null, and when it is - all Java-Doc Pages will have their respective source-code files hilited, and will have links such links placed on their their pages.
The filter-parameter ('cietNameFilter'
) that needs to be passed here is just a JavaPredicate<String>
. ThisPredicate's 'test(String)'
method will receive the fully-qualified name of a JavaClass, Interface,
orEnum
(CIET) whose source-code documentation-file is being Code-HiLited.
ThePredicate
should returnTRUE
if you would like to see the original Java Source-Code ('.java'
file) HiLited, andFALSE
if the Upgrader should skip the CIET.
NOTE: If you keep a short'.txt'
file that just lists the classes you don't want hilited, you may load that'.txt'
file into a JavaPredicate
using either:
TheHiLited Source Code File
procedure is the one which creates links on your Java Doc Pages that look like:- Parameters:
cietNameFilter
- The file-name filter. Thisjava.lang.Predicate<String>
needs to accept or reject the fully qualified name of aClass, Interface,
orEnum
.- See Also:
doNotHiLiteSourceCodeFiles()
,hiLiteSourceCodeFileFilter
,StrFilter
- Code:
- Exact Method Body:
1
this.hiLiteSourceCodeFileFilter = RAW_TYPES_FIX(cietNameFilter); return this;
-
setHiLiteAllMethodsFilter
public Upgrade setHiLiteAllMethodsFilter (java.util.function.Predicate<? super java.lang.String> cietNameFilter)
This filter decides which Java-Doc Web-Pages will have all their method-bodies hilited and inserted into the JavaDoc Page. By default this field is'null'
, and when it is - all Java-Doc Pages will have their respective method-bodies (Java Source) hilited and inserted into the page.
The filter-parameter ('cietNameFilter'
) that needs to be passed here is just a JavaPredicate<String>
. ThisPredicate's 'test(String)'
method will receive the fully-qualified name of a JavaClass, Interface,
orEnum
(CIET) whose source-code documentation-file is being Code-HiLited.
ThePredicate
should returnTRUE
if you would like to see the Method Bodies HiLited, andFALSE
if the Upgrader should skip hiliting method bodies for the CIET.
NOTE: If you keep a short'.txt'
file that just lists the classes you don't want hilited, you may load that'.txt'
file into a JavaPredicate
using either:
TheHiLite Method Body
procedure is the one which creates segments on your Java Doc Pages that look like:- Parameters:
cietNameFilter
- The file-name filter. Thisjava.lang.Predicate<String>
needs to accept or reject the fully qualified name of aClass, Interface,
orEnum
.- See Also:
doNotHiLiteMethods()
,hiLiteAllMethodsFilter
,StrFilter
- Code:
- Exact Method Body:
1
this.hiLiteAllMethodsFilter = RAW_TYPES_FIX(cietNameFilter); return this;
-
setHiLiteAllFieldsFilter
public Upgrade setHiLiteAllFieldsFilter (java.util.function.Predicate<? super java.lang.String> cietNameFilter)
This filter decides which Java-Doc Web-Pages will have all their field-declarations hilited, and the hilited-code inserted into the JavaDoc Page. By default this field is null, and when it is - all Java-Doc Pages will have their respective source-code field-declarations hilited and inserted onto their page.
The filter-parameter ('cietNameFilter'
) that needs to be passed here is just a JavaPredicate<String>
. ThisPredicate's 'test(String)'
method will receive the fully-qualified name of a JavaClass, Interface,
orEnum
(CIET) whose source-code documentation-file is being Code-HiLited.
ThePredicate
should returnTRUE
if you would like to see the Field Declarations HiLited, andFALSE
if the Upgrader should skip hiliting field declarations for the CIET.
NOTE: If you keep a short'.txt'
file that just lists the classes you don't want hilited, you may load that'.txt'
file into a JavaPredicate
using either:
TheHiLite Field Declaration
procedure is the one which creates segments on your Java Doc Pages that look like:- Parameters:
cietNameFilter
- The file-name filter. Thisjava.lang.Predicate<String>
needs to accept or reject the fully qualified name of aClass, Interface,
orEnum
.- See Also:
doNotHiLiteFields()
,hiLiteAllFieldsFilter
,StrFilter
- Code:
- Exact Method Body:
1
this.hiLiteAllFieldsFilter = RAW_TYPES_FIX(cietNameFilter); return this;
-
setHiLiteAllConstructorsFilter
public Upgrade setHiLiteAllConstructorsFilter (java.util.function.Predicate<? super java.lang.String> cietNameFilter)
This filter decides which Java-Doc Web-Pages will have all their constructor-declarations hilited, and the hilited-code inserted into the JavaDoc Page. By default this constructor is null, and when it is - all Java-Doc Pages will have their respective source-code constructor-declarations hilited and inserted onto their page.
The filter-parameter ('cietNameFilter'
) that needs to be passed here is just a JavaPredicate<String>
. ThisPredicate's 'test(String)'
method will receive the fully-qualified name of a JavaClass
orEnum
(CIET) whose source-code documentation-file is being Code-HiLited.
ThePredicate
should returnTRUE
if you would like to see the Constructor Declarations HiLited, andFALSE
if the Upgrader should skip hiliting constructor declarations for the CIET.
NOTE: If you keep a short'.txt'
file that just lists the classes you don't want hilited, you may load that'.txt'
file into a JavaPredicate
using either:
TheHiLite Constructor Declaration
procedure is the one which creates segments on your Java Doc Pages that look like:- Parameters:
cietNameFilter
- The file-name filter. Thisjava.lang.Predicate<String>
needs to accept or reject the fully qualified name of aClass
orEnum
.- See Also:
hiLiteConstructors()
,hiLiteAllConstructorsFilter
,StrFilter
- Code:
- Exact Method Body:
1
this.hiLiteAllConstructorsFilter = RAW_TYPES_FIX(cietNameFilter); return this;
-
setCSSTagsFilter
public Upgrade setCSSTagsFilter (java.util.function.Predicate<? super java.lang.String> cietNameFilter)
This filter decides which Java-Doc Web-Pages will have internal Java-Doc HTML Elements updated to contain a series ofCSS 'CLASS'
andCSS 'ID'
tags. These tags may then be used with an external CSS-StyleSheet, which makes the task of adding color, font, and border-designs to a Java-Doc Page a lot easier. By default, this field is null - and all pages will haveCSS Tags
inserted.
The filter-parameter ('cietNameFilter'
) that needs to be passed here is just a JavaPredicate<String>
. ThisPredicate's 'test(String)'
method will receive the fully-qualified name of a JavaClass, Interface,
orEnum
(CIET) whose source-code documentation-file is being Code-HiLited.
ThePredicate
should returnTRUE
if you would like to see CSS Tags inserted into the HTML, andFALSE
if the Upgrader should skip insertingCSS Tags
into this CIET.
TheInsert CSS Tags
procedure is the one which createsCSS CLASS
attributes in your Java Doc Pages that look:
NOTE: If you keep a short'.txt'
file that just lists the classes you don't want changed, you may load that'.txt'
file into a JavaPredicate
using either:
The defaultCSS File
used by this upgrader may be viewed here:
Default CSS File- Parameters:
cietNameFilter
- The file-name filter. Thisjava.lang.Predicate<String>
needs to accept or reject the fully qualified name of aClass, Interface,
orEnum
.- See Also:
doNotAddCSSTags()
,cssTagsFilter
,StrFilter
- Code:
- Exact Method Body:
1
this.cssTagsFilter = RAW_TYPES_FIX(cietNameFilter); return this;
-
doNotRemoveSummaries
public Upgrade doNotRemoveSummaries()
This will set a filterPredicate
that returnsFALSE
for everyClass, Interface
orEnum
. If this method is used, then none of the Java-Doc Upgraded Pages will have theirSummaries
(at the top of a Java Doc'.html'
Page) truncated.
Note that the original Java Doc Tool, itself, doesn't always provide the cleanest of pages when the Comments for aMethod
orField
become very long or intricate. Usually, if HTML of any kind is used in the comments section of a method or field is used, then theMethod Summaries
orField Summaries
may look awfully skewed.- See Also:
summaryRemoveFilter
,setSummaryRemoveFilter(Predicate)
- Code:
- Exact Method Body:
1
this.summaryRemoveFilter = ALWAYS_FALSE; return this;
-
doNotHiLiteSourceCodeFiles
public Upgrade doNotHiLiteSourceCodeFiles()
This will set a filterPredicate
that returnsFALSE
for everyClass, Interface
orEnum
. If this method is used, then none of the Java-Doc Upgraded Pages will have their fullSource Code Files
HiLited. There is usually a link at the top of the Upgraded Pages that allows a user to click and see the original'.java'
source-code.- See Also:
hiLiteSourceCodeFileFilter
,setHiLiteSourceCodeFileFilter(Predicate)
- Code:
- Exact Method Body:
1
this.hiLiteSourceCodeFileFilter = ALWAYS_FALSE; return this;
-
doNotHiLiteMethods
public Upgrade doNotHiLiteMethods()
This will set a filterPredicate
that returnsFALSE
for everyClass, Interface
orEnum
. If this method is used, then none of the Java-Doc Upgraded Pages will have theirMethod Bodies
HiLited.- See Also:
hiLiteAllMethodsFilter
,setHiLiteAllMethodsFilter(Predicate)
- Code:
- Exact Method Body:
1
this.hiLiteAllMethodsFilter = ALWAYS_FALSE; return this;
-
doNotHiLiteFields
public Upgrade doNotHiLiteFields()
This will set a filterPredicate
that returnsFALSE
for everyClass, Interface
orEnum
. If this method is used, then none of the Java-Doc Upgraded Pages will have theirField Declarations
HiLited.- See Also:
hiLiteAllFieldsFilter
,setHiLiteAllFieldsFilter(Predicate)
- Code:
- Exact Method Body:
1
this.hiLiteAllFieldsFilter = ALWAYS_FALSE; return this;
-
hiLiteConstructors
public Upgrade hiLiteConstructors()
Differing fromFields
andMethods
, constructors in an upgraded Java-Doc Page are not automatically hilited. You need to explicity ask the upgrader to hiliteConstructor Bodies
. This method will indicate to the upgrader to hilite theConstructor Bodies
for allclasses
andenums
that it encounter.
This will set a filterPredicate
that returnsTRUE
for everyClass
orEnum
. If this method is used, then all of the Java-Doc Upgraded Pages will have theirConstructor Bodies
HiLited.- See Also:
hiLiteAllConstructorsFilter
,setHiLiteAllConstructorsFilter(Predicate)
- Code:
- Exact Method Body:
1
this.hiLiteAllConstructorsFilter = ALWAYS_TRUE; return this;
-
doNotAddCSSTags
public Upgrade doNotAddCSSTags()
This will set a filterPredicate
that returnsFALSE
for everyClass, Interface
orEnum
. If this method is used, then none of the Java-Doc Upgraded Pages will haveCSS Tags
inserted.
This will make it impossible to employ any of the CSS Colorizing or Font-Changing features made available by this Upgrader.- See Also:
cssTagsFilter
,setCSSTagsFilter(Predicate)
- Code:
- Exact Method Body:
1
this.cssTagsFilter = ALWAYS_FALSE; return this;
-
setEmbedTagsMapFile
public Upgrade setEmbedTagsMapFile(java.lang.String tagIDMapFileName)
Sets anEmbed Tag ID Table
using atext file
on your file-system.
You have the ability to insert HTML'<EMBED>'
tags into the comments of your source-files, because this Upgrader will replace those HTML elements with the HTML found in the file named by this map. See the image below as an example: Notice that all that has to be provided to the tag is a'DATA-FIILE-ID'
. This'ID'
is mapped to a file-systemtext-file
using this map.- Parameters:
tagIDMapFileName
- This text-file should contain lines of text with"DATA-FILE-ID's"
and'.html'
File-Name's - each on a separate line.
TheEmbed Tags Map
for this JAR Build Script (as an example) can be viewed here:
Embed Tags Map File- Returns:
'this' Upgrade
instance - for invocation-chaining.- See Also:
HELPER.readMapFile(String)
,setEmbedTagsMap(java.util.Map<java.lang.String, java.lang.String>)
,embedTagIDTable
- Code:
- Exact Method Body:
1 2
Hashtable<String, String> ret = HELPER.readMapFile(tagIDMapFileName); return setEmbedTagsMap(ret);
-
setEmbedTagsMap
public Upgrade setEmbedTagsMap (java.util.Map<java.lang.String,java.lang.String> tagIDMap)
Sets anEmbed Tag ID Table
using a Javajava.util.Map<tring, String>
. The firstGeneric String-Parameter
of the map is for a'DATA-FILE-ID'
, and the second is expected to hold'.html'
file-names.- Parameters:
tagIDMap
- This should map'DATA-FILE-ID'
to an'.html'
File-Name.- Returns:
'this' Upgrade
instance - for invocation-chaining.- See Also:
UpgradeException.checkFileExistsAndCanAccess(String, String)
,embedTagIDTable
- Code:
- Exact Method Body:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24
embedTagIDTable.clear(); tagIDMap.forEach((String embedTagID, String htmlFileName) -> { try { UpgradeException.checkFileExistsAndCanAccess (htmlFileName, "External HTML Documentation File to Insert"); } catch (Throwable t) { ERROR(t, "There was an error while attempting to load the ID File for ID: " + '[' + C.BCYAN + embedTagID + C.RESET + "]\n" + "Attempting to load File:\n" + C.BYELLOW + htmlFileName + C.RESET ); System.exit(0); } embedTagIDTable.put(embedTagID, htmlFileName); }); return this;
-
useHiLiteServerCache
public Upgrade useHiLiteServerCache(HiLiteMe.Cache cache)
Convenience Method. InvokessetHiLiter(HiLiter)
andHiLiter.getDefault(HiLiteMe.Cache, String, String)
- Code:
- Exact Method Body:
1
setHiLiter(HiLiter.getDefault(cache, "vim", "native")); return this;
-
setHiLiter
public Upgrade setHiLiter(HiLiter hiLiter)
Tells this Upgrader to use a particular'HiLiter'
. The defaultHiLiter
is used if this method isn't invoked. ReplacementHiLiter's
are better explained by theHiLiter
Functional-Interface
- Parameters:
hiLiter
- This should be any implementation of the'HiLiter'
.- Returns:
'this' Upgrade
instance - for invocation-chaining.- See Also:
hiLiter
- Code:
- Exact Method Body:
1
this.hiLiter = hiLiter; return this;
-
retrieveDefaultJDCSSFileFromJAR
public static java.lang.String retrieveDefaultJDCSSFileFromJAR()
Returns the contents of the standard JavaDoc UpgradeCSS File
as aString
.
IMPORTANT: The CSS file that is loaded is actually stored in a data-file within the Java-HTML JAR file library. This string remains, on disk, in the JAR unless this method is invoked. In order to customize the CSS to your liking, please review theString
that is returned by this method. The fonts, colors, and styles that are produced by the default CSS file are the ones used in this documentation page that you are reading right now. These font, color, and style CSS definitions may be changed by retrieving this CSS definition page (as ajava.lang.String
, and saving thatString
to a file). Once the standard-issue CSS has been modified to fit your needs, using the new-updated definitions is done by invokingsetCustomJDCSSFile(String)
.
NOTE: The actualCLASS
andID
tags inserted by this tool cannot be changed - only the definitions (fonts, colors, & styles) may be modified. The actual'.css'
file retrieved (as ajava.lang.String
) contains much explanation and commenting for each of theCLASS
andID
tags defined on the page. Again, save thisString
to disk, and look at it. If it looks like some of the definitions could look better, modify them and then pass the updated'.css'
file to methodsetCustomJDCSSFile(String)
.
STATIC METHOD: This method may be invoked at any time, it does not require an instance of'Upgrade'
to be running. Reviewing CSS can be complicated, and changing the code 'off-line' is encouraged.
FINALLY: The documentation forclass Colorize
also has a detailed explanation for each of theCLASS
andID
definitions inserted by this upgrader tool. Thisclass
should also be reviewed if the comments and documentation included in theString
/ file returned by this method are insufficient for understanding what is happening.
The defaultCSS File
used by this upgrader may be viewed here:
Default CSS File- Returns:
- A
CSS File
which utilizes the addedCSS
Colorize
CLASSES
. The actual file is read from disk, and returned as aString
. - See Also:
LFEC.readObjectFromFile_JAR(Class, String, boolean, Class)
,setCustomJDCSSFile(String)
,Colorize
,jdCSS
- Code:
- Exact Method Body:
1 2
return LFEC.readObjectFromFile_JAR (Torello.Data.DataFileLoader.class, "data14.sdat", true, String.class);
-
setCustomJDCSSFile
public Upgrade setCustomJDCSSFile(java.lang.String CSSFileAsAString)
Set's the CSS Definitions file to a custom-made CSS file.
IMPORTANT: The actual CSSCLASS
Names andID
Tag's cannot be changed in this file. The styles, colors, fonts may be modified, added and deleted as needed by the ultimate design-choices. However, there is no way to changeCLASS
orID
names of the CSS tags that are inserted.
NOTE: The Upgrader Tool's methodretrieveDefaultJDCSSFileFromJAR()
will return the complete CSS definition'.css'
file. Review that method's documentation for more information. Save thatjava.lang.String
to a file on your file-system, and then update it or modify it to suit your projects design choices. Afterwards, pass that file as ajava.lang.String
to this method - and your updated CSS style-definitions will be incorporated into the JavaDoc pages produced by this Upgrader Tool.
AGAIN: The parameter to this method expects theCSS File
to be loaded into aString
, this method is not requesting a file-name!- Parameters:
CSSFileAsAString
- This parameter can be used to associate a custom CSS definition file with the javadoc output that is generated. The entire contents of theCSS File
as ajava.lang.String
- must be passed as input to this method.- Returns:
'this' Upgrade
instance - for invocation-chaining.- See Also:
jdCSS
,retrieveDefaultJDCSSFileFromJAR()
,Colorize
- Code:
- Exact Method Body:
1
this.jdCSS = CSSFileAsAString; return this;
-
setFaviconFileFormat
public Upgrade setFaviconFileFormat(IF faviconFileFormat)
This is how to request that a favicon be added to all Java Doc Web-Pages. The file-format is just the favicon's image-type (.jpg, .png
, etc...)- Parameters:
faviconFileFormat
- The file-format for the favicon-file.
NOTE: The favicon file-name must be'favicon'
- Returns:
'this' Upgrade
instance - for invocation-chaining.- See Also:
faviconImageFileName
- Code:
- Exact Method Body:
1 2
this.faviconImageFileName = FAVICON_FILE_NAME + '.' + faviconFileFormat.toString(); return this;
-
printStats
public Upgrade printStats(boolean print)
If you do not want the statistics printed to terminal at the end of the upgrade, passFALSE
to this method. By default, the computed-statistics are printed when the upgrade has finished.- Parameters:
print
- This informs the Upgrader whether you would like to see theStats
at the end of the upgrade. The default value for this field isTRUE
- Returns:
'this' Upgrade
instance - for invocation-chaining.- See Also:
printStats
- Code:
- Exact Method Body:
1
this.printStats = print; return this;
-
setCheckBalance
public Upgrade setCheckBalance(boolean checkBalance)
Turns the HTML balance-checker logic on or off. Read more about balance-checking in the documentation for field checkBalance, or in the class Torello.HTML.Balance. By default, this field is set to'TRUE'
.- Parameters:
checkBalance
- The value of this parameter can turn the balance checker on or off. The default value of the internal'checkBalance'
flag isTRUE
.- Returns:
'this' Upgrade
instance - for invocation-chaining.- See Also:
checkBalance
- Code:
- Exact Method Body:
1
this.checkBalance = checkBalance; return this;
-
setExtraTasks
public Upgrade setExtraTasks (java.util.function.Consumer<CommonParamRecord> extraTasks)
This allows a user to do his own, user-specified tasks to a java-doc vectorized-html page before it is written to disk. The "Extra Tasks"'Consumer'
will receive the same data that all of the primary-operations classes in this Upgrader package receive. To read all of the available datum that is retrieved for each Java Doc Class, Interface & Enumerated-Type, see the class CommonParamRecord.
NOTE: Somewhat similar to theDoclet
feature, when the Upgrader is provided anExtra Tasks
, the user may modify the JavaDoc page in any arbitrary way he chooses. The page is passed as a parsed HTML File.
IMPORTANT: Make sure that any changes made are, indeed, made to the'fileVec'
field of theCommonParamRecord
class. Othereise, those changes will not be reflected in the output Java Doc HTML Page.- Parameters:
extraTasks
- This function-pointer may be used to, sort-of, do extra processing on a JavaDoc HTML Documentation File while the vectorized-html file is already loaded into memory - and parsed. Make sure that whateverConsumer
is passed performs its modifications to the HTML on the vectorized-HTML fieldCommonParamRecord.fileVec
inside the classCommonParamRecord
- Returns:
'this' Upgrade
instance - for invocation-chaining.- See Also:
extraTasks
- Code:
- Exact Method Body:
1
this.extraTasks = extraTasks; return this;
-
setPackageSummaryCleaner
public Upgrade setPackageSummaryCleaner (java.util.function.Consumer<java.util.Vector<HTMLNode>> packageSummaryCleaner)
Sets the cleaner. This is very simple concept, but it may be complex to implement. Java's 'AI' for putting a one-line or one-sentence summary as a description into the "Summary Pages" for Java Packages is sometimes horribly skewed. This occurs if there is any HTML inside a Java Doc Comment.
The best way to learn to use thisConsumer<Vector>
is to try writing a simple that just prints the HTML to the termainl, and see what can be done with it. The size of the problem is limited by how much code-comments you have put into the comment portions of the method's and field's in your source code files.
Try looking at the default-cleaner for this library. Since there is a Very large amount of documentation and code-comments (since this is actually a code-commenting package), the cleaner is a little difficult to understand - although what it is doing is very easy stuff. The default cleaner is linked below:
CleanPackageSummaries.defaultCleaner(Vector)
- Parameters:
packageSummaryCleaner
- This should be any lambda or method that will clean theCIET
HTML descriptions so they aren't skewed.- Returns:
'this' Upgrade
instance - for invocation-chaining.- See Also:
packageSummaryCleaner
- Code:
- Exact Method Body:
1
this.packageSummaryCleaner = packageSummaryCleaner; return this;
-
useDefaultPackageSummaryCleaner
public Upgrade useDefaultPackageSummaryCleaner()
The default Package Description Summary Page Cleaner.- Returns:
'this' Upgrade
instance - for invocation-chaining.- See Also:
CleanPackageSummaries.defaultCleaner(java.util.Vector<Torello.HTML.HTMLNode>)
,packageSummaryCleaner
- Code:
- Exact Method Body:
1
this.packageSummaryCleaner = CleanPackageSummaries::defaultCleaner; return this;
-
setPackageFrames
public Upgrade setPackageFrames(java.lang.String[] packages, java.lang.String[][] sectionNames, java.lang.String[][][] sectionContents, boolean usesFrames)
This is a sample of what the input arrays should look like. This is the "Rearrange Frames" class used to build the Java HTML Library. The file is quite long, however, at the end of this class (below), the fields are collated into arrays so that they may be passed to this method.Torello.Build.Helper.PackageItems.java
- Parameters:
packages
- The list of packages as aString
-ArraysectionNames
- A Two-DimensionalString
-Array that is parallel to the previous'packages'
parameter. Each sub-array here should contain the list of section names for the package in the parallel array.sectionContents
- A Three-DimensionalString
-Array. The first dimension is parallel to both of the other two input array-parameters. Each of the sub-two-dimensional arrays merely / simply (this is not rocket-science) contains a list of classes (and interfaces, enum's, exceptions, etc...) that you want inside the "section" identified by the corresponding element of the'sectionNames'
-array.usesFrames
- By default this method will re-arrange the classes, interfaces, etc... that are listed on the'package-summary.html'
pages. If you have opted to request JavaDoc produce'package-frame.html'
files, passTRUE
to this method, and those files will also be re-arranged- Returns:
'this' Upgrade
instance - for invocation-chaining.- Throws:
ParallelArrayException
- If any of these three arrays aren't of equal lengths!java.lang.NullPointerException
- If any of these arrays contain any'null'
values- See Also:
rearrangeFrames
- Code:
- Exact Method Body:
1 2 3 4
this.rearrangeFrames = new RearrangePkgFrame.PackageItems (packages, sectionNames, sectionContents, usesFrames); return this;
-
setSummaryRearrange
public Upgrade setSummaryRearrange (java.lang.String[] ciets, java.lang.String[][] sectionNames, FCM[] sections, java.util.function.ToIntFunction[] sorters)
This sets the Summary Section Rearrange Logic. Below is a sample of what the arrays should look like in order for this upgrader to perform such an upgrade. This is the "Rearrange Summaries" list of arrays used to build the Java HTML Library. This file is quite long, but reading might make it easier to understand what actually belongs inside these arrays. At the very end of the class in this link, the arrays are collated so that they may be passed here.
Torello.Build.Helper.SummRearrange.java- Parameters:
ciets
- The list of classes, interfaces and enumerated-types having a summary section to be rearranged during the upgrade.sectionNames
- This lists the names into which the table-rows should be sorted for each of the ciets.sections
- For eachj of the CIET's passed in the first array, this identifies whether the particularly summary to be re-arranged is aField, Constructor
orMethod
.sorters
- These sort the FCM's.- Returns:
'this' Upgrade
instance - for invocation-chaining.- Throws:
ParallelArrayException
- If any of these three arrays aren't of equal lengths!java.lang.NullPointerException
- If any of these arrays contain any'null'
values- See Also:
summaryItems
- Code:
- Exact Method Body:
1 2 3 4
this.summaryItems = new RearrangeSummaries.SummaryItems (ciets, sectionNames, sections, sorters, rootSourceFileDirectory); return this;
-
upgrade
public Stats upgrade(StorageWriter sw)
After all parameters have been set with this "JavaDoc Upgrader" (builder)... this method should be invoked to do the processing. This runs the upgradeer for all Java Doc'.html'
Files.- Parameters:
sw
- This is the log.- Returns:
- This returns the statistics computed for the upgrade process. See the class
Stats
for more information. The stats are also printed to the output-stream (StorageWriter
) at the end of the upgrade / build process. - Throws:
UpgradeException
- An unchecked exception. (RuntimeException
)JavaDocError
- If there any I/O errors, or other problems. Review the detailed messages provided - and possibly theThrowable.getCause()
.- Code:
- Exact Method Body:
1 2 3 4 5 6
try { upgradeWithThrows(sw); } catch (Throwable t) { ERROR(t, "There was an error while running the Upgrader."); } return stats;
-
run
public void run(java.lang.String jdFileName, StorageWriter sw)
This runs the Java-Doc Upgrade Mechanism for a single Java Doc'.html'
file- Parameters:
jdFileName
- This is the File-System File-Name of the Java-Doc HTML Web-Page File.sw
- This is a log. This parameter may not be null. If you do not require any log information, then simply setStorageWriter.sysOut
toFALSE
.- Throws:
UpgradeException
- An unchecked exception. (RuntimeException
)JavaDocError
- If there any I/O errors, or other problems. Review the detailed messages provided - and possibly theThrowable.getCause()
.- Code:
- Exact Method Body:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289
String file = null; // ***************************************** // ********* Collect the Garbage *********** // ***************************************** if ((++gcCount % 7) == 0) { System.gc(); } String freeMem = StringParse.commas(rt.freeMemory()); String totalMem = StringParse.commas(rt.totalMemory()); if (VERBOSE_PRINT_STEPS) sw.println( "\n\n**************************************************************************" + '\n' + StringParse.rightSpacePad("Free Memory Available:", 35) + C.BBLUE + freeMem + C.RESET + '\n' + StringParse.rightSpacePad("Total Memory Available:", 35) + C.BBLUE + totalMem + C.RESET ); // ***************************************** // *********** Load JavaDoc File *********** // ***************************************** sw.println (StringParse.rightSpacePad("Loading File:", 35) + C.BYELLOW + jdFileName + C.RESET); try { file = FileRW.loadFileToString(jdFileName); } catch (Throwable t) // (IOException ioe) { ERROR(t, "Failed to load File: " + C.BYELLOW + jdFileName + C.RESET); } Vector<HTMLNode> fileVec = HTMLPage.getPageTokens(file, false); // ***************************************** // ********** Get File Information ********* // ***************************************** // Retrieves the CIET Name with Package Information, and the simple "File-Name" Ret2<String, String> r2 = HELPER.getFullNameAndSourceFileName(fileVec); String cietFullName = r2.a; String srcCodeFileName = rootSourceFileDirectory + r2.b; String dotDots = StringParse.dotDots(jdFileName, rootJavaDocDirectory, FSEP); sw.println( StringParse.rightSpacePad("Fully-Qualified Name:", 35) + C.BYELLOW + cietFullName + C.RESET + '\n' + StringParse.rightSpacePad("Built from Source-File:", 35) + C.BYELLOW + srcCodeFileName + C.RESET + '\n' + StringParse.rightSpacePad("Relative-URL String:", 35) + C.BYELLOW + dotDots + C.RESET ); // ***************************************** // *********** JavaDocHTMLFile ************* // ***************************************** JavaDocHTMLFile jdhf = null; try { jdhf = new JavaDocHTMLFile(fileVec, jdFileName, sw); } catch (Throwable t) // (IOException ioe) { ERROR(t, "Cannot parse Java Doc HTML File:\n" + C.BYELLOW + jdFileName + C.RESET); } String listJDHF = StrCSV.toCSV(jdhf.getGenericParameters(), true, true, null); sw.println( StringParse.rightSpacePad("Parsed JavaDoc '.html':", 35) + "Name [" + C.BYELLOW + jdhf.name + C.RESET + "], " + "Package [" + C.BYELLOW + jdhf.packageName + C.RESET + "], " + "CIET [" + C.BYELLOW + jdhf.ciet + C.RESET + "]" + ((listJDHF.length() > 0) ? ('\n' + StringParse.rightSpacePad("Generic-Parameters Found: ", 35) + listJDHF) : "") ); // ***************************************** // ********* JavaSourceCodeFile ************ // ***************************************** String srcCodeAsStr = null; JavaSourceCodeFile jscf = null; try { srcCodeAsStr = FileRW.loadFileToString(srcCodeFileName); } catch (Throwable t) // (IOException ioe) { ERROR(t, "Unable to load file:\n" + C.BYELLOW + srcCodeFileName + C.RESET + "\n" + "Currently Processing JavaDoc HTML Page:\n" + C.BYELLOW + jdFileName + C.RESET ); } jscf = JavaSourceCodeFile.parse(srcCodeAsStr, srcCodeFileName, jdhf.name, jdhf.ciet); String listJSCF = StrCSV.toCSV(jscf.getGenericParameters(), true, true, null); sw.println( StringParse.rightSpacePad("Parsed Source '.java':", 35) + "Name [" + C.BYELLOW + jscf.name + C.RESET + "], " + "Package [" + C.BYELLOW + jscf.packageName + C.RESET + "], " + "CIET [" + C.BYELLOW + jscf.ciet + C.RESET + "]" + ((listJSCF.length() > 0) ? ('\n' + StringParse.rightSpacePad("Generic-Parameters Found: ", 35) + listJSCF) : "") ); // ***************************************** // ********* Print Parser Find's *********** // ***************************************** sw.println( StringParse.rightSpacePad("'.html' File Parser Found:", 35) + '[' + C.BBLUE + StringParse.zeroPad(jdhf.numFields()) + C.RESET + "] Fields, " + '[' + C.BBLUE + StringParse.zeroPad(jdhf.numConstructors()) + C.RESET + "] Constructors, " + '[' + C.BBLUE + StringParse.zeroPad(jdhf.numMethods()) + C.RESET + "] Methods" ); sw.println( StringParse.rightSpacePad("'.java' File, JavaParser Found:", 35) + '[' + C.BBLUE + StringParse.zeroPad(jscf.numFields()) + C.RESET + "] Fields, " + '[' + C.BBLUE + StringParse.zeroPad(jscf.numConstructors()) + C.RESET + "] Constructors, " + '[' + C.BBLUE + StringParse.zeroPad(jscf.numMethods()) + C.RESET + "] Methods" ); sw.println("**************************************************************************"); // ***************************************** // ********* Main Operations Setup ********* // ***************************************** // Every single one of the "Primary Operations" (below, there are TEN of them) basically // take the same (rather long) list of parameters. This silly little class just // encapsulates them all into a single-parameter... No More, No Less! CommonParamRecord pr = new CommonParamRecord( fileVec, cietFullName, jscf, jdhf, jdFileName, srcCodeFileName, hiLiter, embedTagIDTable, // This one is only used by EmbedTags srcCodeAsStr, dotDots, faviconImageFileName, // Only used by HiLiteSrcCodeFile VERBOSE_PRINT_STEPS ? sw : null, stats ); boolean hlscf = (hiLiteSourceCodeFileFilter == null) || hiLiteSourceCodeFileFilter.test(cietFullName); boolean sr = (summaryRemoveFilter == null) || summaryRemoveFilter.test(cietFullName); boolean hlf = (hiLiteAllFieldsFilter == null) || hiLiteAllFieldsFilter.test(cietFullName); boolean hlm = (hiLiteAllMethodsFilter == null) || hiLiteAllMethodsFilter.test(cietFullName); boolean csst = (cssTagsFilter == null) || cssTagsFilter.test(cietFullName); boolean hlc = (hiLiteAllConstructorsFilter != null) && hiLiteAllConstructorsFilter.test(cietFullName); // ***************************************** // ************ Main Operations ************ // ***************************************** int numHiLitedFields = 0, numHiLitedMethods = 0; int numHiLitedConstructors = 0, numHiLitedDivs = 0; if (hlscf) HiLiteSrcCodeFile.run(pr); else sw.println( "HiLiteSourceCodeFile.run(...)" + C.RESET + "\n\t" + C.BBLUE + " was not called, as per request." + C.RESET ); if (sr) CleanSummaries.removeAllDescriptionsFromSummaries(pr); else sw.println( "CleanSummaries.removeAllDescriptionsFromSummaries(...)" + "\n\t" + C.BBLUE + " was not called, as per request." + C.RESET ); EmbedTag.run(pr); numHiLitedDivs = HiLiteDividers.run(pr); if (hlf) numHiLitedFields = HiLiteFields.run(pr); else sw.println( "HiLiteFields.run(...)" + C.RESET + "\n\t" + C.BBLUE + " was not called, as per request." + C.RESET ); if (hlm) numHiLitedMethods = HiLiteMethods.run(pr); else sw.println( "HiLiteMethods.run(...)" + C.RESET + "\n\t" + C.BBLUE + " was not called, as per request." + C.RESET ); SkewedParameters.run(pr); if (csst) Colorize.run(pr); else sw.println( "Colorize.run(...)" + C.RESET + "\n\t" + C.BBLUE + " was not called, as per request." + C.RESET ); // The default is to skip "HiLiteConstructors" - so, therefore, no message is needed if (hlc) numHiLitedConstructors = HiLiteConstructors.run(pr); sw.println("Other:"); if (summaryItems != null) RearrangeSummaries.run(pr, summaryItems); if (pr.jscf.staticFunctionalAnnotation) StatelessClasses.run(pr); Convenience.checkForConvenienceMethods(fileVec, sw); Convenience.checkForConvenienceConstructors(fileVec, sw); stats.run(pr, numHiLitedMethods, numHiLitedConstructors, numHiLitedFields, numHiLitedDivs); // ***************************************** // ************* HTML <HEAD> *************** // ***************************************** Features.insertCSSLink(fileVec, dotDots + JAVA_DOC_CSS_FILE_NAME); sw.println( "\t" + StringParse.rightSpacePad("Inserted: CSS-Definitions Relative-Link:", 45) + "'" + C.BYELLOW + dotDots + JAVA_DOC_CSS_FILE_NAME + C.RESET + "' " ); if (faviconImageFileName != null) { Features.insertFavicon(fileVec, dotDots + faviconImageFileName); sw.println( "\t" + StringParse.rightSpacePad("Inserted Favicon Relative-Link:", 45) + "'" + C.BYELLOW + dotDots + faviconImageFileName + C.RESET + "'" ); } else sw.println ("\tFavicon Relative-Link " + "\n\t" + C.BBLUE + "was not inserted, as per request."); if (extraTasks != null) extraTasks.accept(pr); // ***************************************** // *********** HTML Tag Balance ************ // ***************************************** if (checkBalance) { Hashtable<String, Integer> b = Balance.checkNonZero(Balance.check(fileVec)); if (b.size() == 0) sw.println ("Balance-Report:\n\tAll non-singleton tags are balanced."); else ERROR( new BalancedHTMLException ("File: " + jdFileName + " had unbalanced HTML tags.", b), "HTML Balance Error while processing file:\n" + C.BYELLOW + jdFileName + C.RESET ); } // ***************************************** // ****** ReWrite JDFile File to Disk ****** // ***************************************** sw.println("Re-Writing File Back to Disk: " + C.BYELLOW + jdFileName + C.RESET); try { FileRW.writeFile(Util.pageToString(fileVec), jdFileName); } catch (Throwable t) // (Exception e) { ERROR(t, "Failed to write File: " + C.BYELLOW + jdFileName + C.RESET); } // ***************************************** // ************ Write log data ************* // ***************************************** if (logFile != null) { String temp = C.toHTML(sw.getString(), true, true, true).replace("\t", " "); logFile.accept(temp + "\n\n"); sw.erase(); }
-
main
public static void main(java.lang.String[] argv) throws java.lang.Exception
SIMPLIFIED COMMAND LINE OPERATION.
This method contains a section of the contents of the Java-HTML library build-script. All of the lines are commented out, but the JavaDoc Upgrade Tool's use is exhibited. This is a 'main' method, so it therefore may be run from the command-line by calling the "Upgrade" tool's class at the command line. It will read the first agrument and the second argument as:argv[0]:
(REQUIRED) The output java-doc directoryargv[1]:
(OPTIONAL) TheHiLiteMe
Cache Directory
REMEMBER: The most important point is that the actual javadoc utility must have already been invoked on the source-code that is to be hilited before the upgrade tool can be invoked! Below is the command line for building the Java-HTML libraries initial javadoc pages (before they are upgraded by this tool.)
1 2 3 4 5 6 7 8 9 10
public static final String[] jdCommand = { "javadoc", "Torello.Java", "Torello.Java.Additional", "Torello.Java.Function", "Torello.HTML", "Torello.HTML.NodeSearch", "Torello.HTML.Tools.JavaDoc", "Torello.HTML.Tools.NewsSite", "Torello.HTML.Tools.Images", "Torello.Languages", "Torello.REST" "-d", "javadoc", "-docfilessubdirs", "-linksource", "-docencoding", "UTF-8", "-charset", "UTF-8", "--allow-script-in-comments", "-sourcetab", "4" };
CACHE-INITIALIZING: In order to build a "HiLite.ME Cache", or to clear an over-used cache which after much use could be emptied - all that is needed to is to make sure that the directory where the cache is to be placed does not exist and has been deleted. When the specified "HiLite Cache Directory" has been fully removed from the file-system, the Upgrade Tool will build an empty CACHE, and begin to save the hilited code (retrieved from HiLite.ME) in the local file-system so that the same code does not need to be processed again and again. When the directory has been fully erased (and removed, completely), the Upgrade Tool will build a new'HILITED_STRINGS_HASH_CODE.ts'
file and also create the necessary directory to store the saved-files in that directory.
EXAMPLE USE: While looking for a good java-based spell checker, this package came up. After downloading the source-code files to the local file-system, the following two commands produced an "Upgraded Java-Doc" experience. The first line below will run the standard javadoc utility, and leave the contents in directory "~/javadoc/". The second command will "Upgrade" the tool by inserted code-hiliting, adding CSS Names, and adding a favicon. Remember, to alter the colors, the CSS file that's left in the output directory, "~/javadoc/JavaDoc.css" can be modified and altered to make the colors, shapes, etc... in line with the project.
UNIX or DOS Shell Command:cloudshell:~$ cloudshell:~$ javadoc com.inet.jortho com.inet.jorthodictionaries -d javadoc -docfilessubdirs -linksource -docencoding "UTF-8" -charset "UTF-8" --frames --allow-script-in-comments -sourcetab 4 cloudshell:~$ java Torello.HTML.Tools.JavaDoc.Upgrade javadoc/ jdcache/
- Parameters:
argv
- This is the argument received from the command line.- Throws:
java.lang.Exception
- Code:
- Exact Method Body:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
StorageWriter sw = new StorageWriter(); Upgrade upgrader = new Upgrade(argv[0], ""); if (argv.length == 1) upgrader.upgrade(sw); else if (argv.length == 2) { java.io.File f = new java.io.File(argv[1]); if (! f.exists()) { f.mkdirs(); Cache.initializeOrClear(argv[1], sw); } Cache CACHE = new Cache(argv[1]); upgrader.useHiLiteServerCache(CACHE).upgrade(sw); CACHE.persistMasterHashToDisk(); } else System.out.println("Failed, expected one or two arguments");
-
-