001package Torello.Java.Build;
002
003import Torello.JavaDoc.PackageSummaryHTML;
004
005import Torello.Java.Additional.BiAppendable;
006
007import Torello.Java.FileNode;
008import Torello.Java.FileTransfer;
009import Torello.Java.Shell;
010import Torello.Java.OSResponse;
011import Torello.Java.StrPrint;
012
013import Torello.Java.ReadOnly.ReadOnlyList;
014import Torello.Java.ReadOnly.ROArrayListBuilder;
015
016import static Torello.Java.C.*;
017
018import java.io.IOException;
019import java.io.File;
020
021/**
022 * This is the second Build-Stage, and it runs the Standard Java-Doc Tool - using {@code 'javadoc'}
023 * and {@link Shell Torello.Java.Shell}.  This class also relies heavily on the Java-HTML Tools
024 * {@link FileNode} and {@link FileTransfer}.
025 * 
026 * <EMBED CLASS=external-html DATA-FILE-ID=STAGE_PRIVATE_NOTE>
027 * <EMBED CLASS='external-html' DATA-FILE-ID=S02_JAVADOC>
028 */
029@Torello.JavaDoc.StaticFunctional
030public class S02_JavaDoc
031{
032    // Completely irrelevant, and the 'private' modifier keeps it off of JavaDoc
033    private S02_JavaDoc() { }
034
035
036    // ********************************************************************************************
037    // ********************************************************************************************
038    // Private-Constant
039    // ********************************************************************************************
040    // ********************************************************************************************
041
042
043    private static final ReadOnlyList<String> commandSwitches(final BuilderRecord brec)
044    {
045        ROArrayListBuilder<String> roalb = new ROArrayListBuilder<>();
046
047        roalb.add("-d");                roalb.add("javadoc");
048        roalb.add("-docfilessubdirs");
049        roalb.add("-linksource");
050        roalb.add("-charset");          roalb.add("UTF-8");
051        roalb.add("-docencoding");      roalb.add("UTF-8");
052        roalb.add("-encoding");         roalb.add("UTF-8");
053        roalb.add("-sourcetab");        roalb.add("4");
054        roalb.add("-splitindex");
055        roalb.add("-notree");
056        roalb.add("-classpath");        roalb.add(brec.CLASS_PATH_STR);
057
058        if ((brec.JAVADOC_VER <= 11) && (! brec.NO_JAVADOC_FRAMES_SWITCH))
059            roalb.add("--frames");
060
061        roalb.add("--allow-script-in-comments");  
062
063        if ((brec.JAVADOC_VER == 11) || (brec.JAVADOC_VER == 14))
064            roalb.add("--no-module-directories");
065
066
067        // The <EMBED> tags and <BR />'s break starting in javdoc version 14.
068        // For now this says "17" because Google Cloud Server only provides java Version 11 & 17
069        // Java 14 is completely missing, so I don't actually now if this is needed for 14!
070
071        if (brec.JAVADOC_VER == 17) roalb.add("-Xdoclint:html");
072
073
074        // "WebSockets" have @since tags... before "The Refl" was fully working, this was needed
075        // "-nosince"
076    
077        // needed for the search bar !
078        // "-overview", "Torello/Build/OverviewSummary.html"
079
080        // This isn't used in Java-HTML, as of January 2024.  However, if there ever arises a need
081        // to quickly add / append command-line switches to the `javadoc` command, it is handled
082        // right here.
083
084        if ((brec.extraSwitchesJAVADOC != null) && (brec.extraSwitchesJAVADOC.size() > 0))
085            for (String switchStr : brec.extraSwitchesJAVADOC)
086                roalb.add(switchStr);
087
088        return roalb.build();
089    };
090
091
092    // ********************************************************************************************
093    // ********************************************************************************************
094    // This Class Main Method: Run Java-Doc
095    // ********************************************************************************************
096    // ********************************************************************************************
097
098
099    public static void javaDoc(final BuilderRecord brec) throws IOException
100    {
101        brec.timers.startStage02();
102
103        Printing.startStep(2);
104
105        // Used for the log
106        final StringBuilder logOnly = new StringBuilder();
107
108        // Prints to both the log and System.out
109        final Appendable logAndScreen = new BiAppendable(logOnly, System.out);
110
111
112        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
113        // First deletes the current 'javadoc/' dir if there happens to be one already
114        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
115
116        logAndScreen.append
117            ("Deleting current directory contents: " + brec.LOCAL_JAVADOC_DIR + "\n\n");
118
119
120        // Printing Out the Complete List of every file that is deleted by this command seems
121        // a little bit excessive.  PRIMARILY - BECAUSE - The text-output that is produced by
122        // 'deleteFilesRecursive' contains the class 'C' UNIX-Colors,  it would be better to just
123        // shunt the output completely.  Remember that the output of the 'javadoc' Stage (This
124        // Stage / Stage-02) is saved to a text-log file.
125
126        if (new File(brec.LOCAL_JAVADOC_DIR).exists())
127            FileTransfer.deleteFilesRecursive
128                (FileNode.createRoot(brec.LOCAL_JAVADOC_DIR).loadTree(), null, null, logOnly);
129
130
131        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
132        // Build & Print the javadoc Command / Arguments
133        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
134
135        logOnly.append("\nPackages Included in this Build:\n\n");
136        for (BuildPackage bp : brec.packageList) logOnly.append(bp.fullName + '\n');
137
138        ReadOnlyList<BuildPackage> packagesToJavaDoc = Packages.packagesToJavaDoc(brec);
139
140        logOnly.append("\nPackages to be Documented by 'javadoc':\n\n");
141        for (BuildPackage bp : brec.packageList) logOnly.append(bp.fullName + '\n');
142
143        // Do this first, it has a little text output that looks better at the top
144        ReadOnlyList<String> filesToJavaDoc = Files.filesToJavaDoc
145            (packagesToJavaDoc, logAndScreen);
146
147        logAndScreen.append(
148            BGREEN + "INVOKING: " + RESET +
149            BYELLOW + brec.JAVADOC_BIN + RESET + "\n"
150        );
151
152        ROArrayListBuilder<String> roalb = new ROArrayListBuilder<>();
153
154        // First append the command switches
155        for (String arg : commandSwitches(brec))
156        {
157            logAndScreen.append((arg.startsWith("-") ? "\n    " : " ") + arg);
158            roalb.add(arg);
159        }
160
161        logAndScreen.append('\n');
162        final int NUM_SWITCHES = roalb.size();
163
164        logAndScreen.append("\n");
165
166        /* Screen Only */ System.out.println(
167            "    [Files List Ommited, Total Number of Files to Document: " +
168            BRED + filesToJavaDoc.size() + RESET + "]\n"
169        );
170
171        // Now append the names of the actual Java Files, themselves
172        for (String fileName : filesToJavaDoc)
173        {
174            roalb.add(fileName);
175            logOnly.append("    " + fileName + '\n');
176        }
177
178        ReadOnlyList<String> javaDocCommand = roalb.build();
179
180
181        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
182        // RUN JAVA-DOC
183        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
184
185        final String[] tempCmdArr = javaDocCommand.toArray(new String[0]);
186
187        int counter = 0;
188        for (String arg : tempCmdArr)
189            logOnly.append(arg + ((++counter > NUM_SWITCHES) ? "\n" : ""));
190
191        OSResponse osr = new Shell(null, null).COMMAND(brec.JAVADOC_BIN, tempCmdArr);
192
193        // CHECK FOR ERRORS - Other than the Uses-Frames Warning-Message
194        if (osr.errorOutput.length() > 0)
195        {
196            System.err.println
197                (BRED + "\nTEXT PRINTED TO STANDARD ERROR:\n" + RESET + osr.errorOutput);
198
199            if (! StrPrint.lastNLines(osr.errorOutput, 7)
200                    .equals(PackageSummaryHTML.JD_FRAMES_WARNING_MESSAGE)) 
201                Util.ERROR_EXIT("javadoc");
202            else
203                // sb.append("NOTE: Frames Warning Ignored.\n");
204                logAndScreen.append("NOTE: Frames Warning Ignored.\n");
205        }
206
207
208        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
209        // Write the log data to the log files
210        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
211
212        brec.logs.write_S02_LOGS(logOnly.toString(), osr.standardOutput, osr.errorOutput);
213        brec.timers.endStage02();
214    }
215}