16  * Creates a Comments from an XML file. The Comments object is the internal 
17  * representation of the comments for the changes.
18  * All methods in this class for populating a Comments object are static.
23 public class Comments {  class
26      * All the possible comments known about, accessible by the commentID.
30     /** The old Comments object which is populated from the file read in. */ 
31     private static Comments oldComments_ = null;
34     public Comments() {  in Comments()  method in Comments
38     // The list of comments elements associated with this objects
42      * Read the file where the XML for comments about the changes between
43      * the old API and new API is stored and create a Comments object for 
44      * it. The Comments object may be null if no file exists.
46     public static Comments readFile(String filename) {  in readFile()
47         // If validation is desired, write out the appropriate comments.xsd   in readFile()
48         // file in the same directory as the comments XML file.  in readFile()
58         // The instance of the Comments object which is populated from the file.   in readFile()
59         oldComments_ = new Comments();  in readFile()
122         xsdFileName += "comments.xsd";  in writeXSD()
126             // The contents of the comments.xsd file  in writeXSD()
132             xsdFile.println("  Schema for JDiff comments.");  in writeXSD()
136             xsdFile.println("<xsd:element name=\"comments\" type=\"commentsType\"/>");  in writeXSD()
167 // Methods to add data to a Comments object. Called by the XML parser and the 
172      * Add the SingleComment object to the list of comments kept by this 
180 // Methods to get data from a Comments object. Called by the report generator
184      * The text placed into XML comments file where there is no comment yet.
193     public static String getComment(Comments comments, String id) {  in getComment()  argument
194         if (comments == null)  in getComment()
197         int idx = Collections.binarySearch(comments.commentsList_, key);  in getComment()
201             int startIdx = comments.commentsList_.indexOf(key);  in getComment()
202             int endIdx = comments.commentsList_.indexOf(key);  in getComment()
205 …System.out.println("Warning: " + numIdx + " identical ids in the existing comments file. Using the…  in getComment()
207             SingleComment singleComment = (SingleComment)(comments.commentsList_.get(idx));  in getComment()
368 // Methods to write a Comments object out to a file.
372      * Write the XML representation of comments to a file.
374      * @param outputFileName The name of the comments file.
375      * @param oldComments The old comments on the changed APIs.
376      * @param newComments The new comments on the changed APIs.
380                                     Comments newComments) {  in writeFile()
397      * Write the Comments object out in XML.
417      * Dump the contents of a Comments object out for inspection.
433      * Emit messages about which comments are now unused and which are new.
435     public static void noteDifferences(Comments oldComments, Comments newComments) {  in noteDifferences()
437             System.out.println("Note: all the comments have been newly generated");  in noteDifferences()
442         // the new comments, marking them as unused.  in noteDifferences()
461         outputFile.println("<comments");  in emitXMLHeader()
463         outputFile.println("  xsi:noNamespaceSchemaLocation='comments.xsd'");  in emitXMLHeader()
482 …outputFile.println("<!-- When the API diffs report is generated, the comments in this file get add…  in emitXMLHeader()
489 …text to appear at each place in the report, but will be converted to separate comments when the ");  in emitXMLHeader()
490         outputFile.println("     comments file is used. -->");  in emitXMLHeader()
506         outputFile.println("</comments>");  in emitXMLFooter()
515      * If you want to be able to use sloppy HTML in your comments, then you can
543      * The file where the XML representing the new Comments object is stored.