Package jdiff

Class Comments

  • public class Comments
extends java.lang.Object
    Creates a Comments from an XML file. The Comments object is the internal representation of the comments for the changes. All methods in this class for populating a Comments object are static. See the file LICENSE.txt for copyright details.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.util.Hashtable allPossibleComments
      All the possible comments known about, accessible by the commentID.
      java.util.List commentsList_  
      static java.lang.String placeHolderText
      The text placed into XML comments file where there is no comment yet.

    • Constructor Summary

      Constructors 
      Constructor Description
      Comments()
      Default constructor.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void addComment​(jdiff.SingleComment comment)
      Add the SingleComment object to the list of comments kept by this object.
      static java.lang.String convertAtLinks​(java.lang.String text, java.lang.String currentElement, jdiff.PackageAPI pkg, jdiff.ClassAPI cls)
      Convert @link tags to HTML links.
      void dump()
      Dump the contents of a Comments object out for inspection.
      void emitComments()
      Write the Comments object out in XML.
      void emitXMLFooter()
      Emit the XML footer.
      void emitXMLHeader​(java.lang.String filename)
      Emit the XML header.
      static java.lang.String getComment​(Comments comments, java.lang.String id)
      Return the comment associated with the given id in the Comment object.
      static boolean isMinimizedTag​(java.lang.String tag)
      Return true if the given HTML tag has no separate end element.
      static void noteDifferences​(Comments oldComments, Comments newComments)
      Emit messages about which comments are now unused and which are new.
      static Comments readFile​(java.lang.String filename)
      Read the file where the XML for comments about the changes between the old API and new API is stored and create a Comments object for it.
      static boolean writeFile​(java.lang.String outputFileName, Comments newComments)
      Write the XML representation of comments to a file.
      static void writeXSD​(java.lang.String filename)
      Write the XML Schema file used for validation.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Field Detail

      • allPossibleComments

        public static java.util.Hashtable allPossibleComments
        All the possible comments known about, accessible by the commentID.

      • commentsList_

        public java.util.List commentsList_

      • placeHolderText

        public static final java.lang.String placeHolderText
        The text placed into XML comments file where there is no comment yet. It never appears in reports.
        See Also:
        Constant Field Values

    • Constructor Detail

      • Comments

        public Comments()
        Default constructor.

    • Method Detail

      • readFile

        public static Comments readFile​(java.lang.String filename)
        Read the file where the XML for comments about the changes between the old API and new API is stored and create a Comments object for it. The Comments object may be null if no file exists.

      • writeXSD

        public static void writeXSD​(java.lang.String filename)
        Write the XML Schema file used for validation.

      • addComment

        public void addComment​(jdiff.SingleComment comment)
        Add the SingleComment object to the list of comments kept by this object.

      • getComment

        public static java.lang.String getComment​(Comments comments,
                                          java.lang.String id)
        Return the comment associated with the given id in the Comment object. If there is no such comment, return the placeHolderText.

      • convertAtLinks

        public static java.lang.String convertAtLinks​(java.lang.String text,
                                              java.lang.String currentElement,
                                              jdiff.PackageAPI pkg,
                                              jdiff.ClassAPI cls)
        Convert @link tags to HTML links.

      • writeFile

        public static boolean writeFile​(java.lang.String outputFileName,
                                Comments newComments)
        Write the XML representation of comments to a file.
        Parameters:
        outputFileName - The name of the comments file.
        oldComments - The old comments on the changed APIs.
        newComments - The new comments on the changed APIs.
        Returns:
        true if no problems encountered

      • emitComments

        public void emitComments()
        Write the Comments object out in XML.

      • dump

        public void dump()
        Dump the contents of a Comments object out for inspection.

      • noteDifferences

        public static void noteDifferences​(Comments oldComments,
                                   Comments newComments)
        Emit messages about which comments are now unused and which are new.

      • emitXMLHeader

        public void emitXMLHeader​(java.lang.String filename)
        Emit the XML header.

      • emitXMLFooter

        public void emitXMLFooter()
        Emit the XML footer.

      • isMinimizedTag

        public static boolean isMinimizedTag​(java.lang.String tag)
        Return true if the given HTML tag has no separate end element. If you want to be able to use sloppy HTML in your comments, then you can add the element, e.g. li back into the condition here. However, if you then become more careful and do provide the closing tag, the output is generally just the closing tag, which is incorrect. tag.equalsIgnoreCase("tr") || // Is sometimes minimized tag.equalsIgnoreCase("th") || // Is sometimes minimized tag.equalsIgnoreCase("td") || // Is sometimes minimized tag.equalsIgnoreCase("dt") || // Is sometimes minimized tag.equalsIgnoreCase("dd") || // Is sometimes minimized tag.equalsIgnoreCase("img") || // Is sometimes minimized tag.equalsIgnoreCase("code") || // Is sometimes minimized (error) tag.equalsIgnoreCase("font") || // Is sometimes minimized (error) tag.equalsIgnoreCase("ul") || // Is sometimes minimized tag.equalsIgnoreCase("ol") || // Is sometimes minimized tag.equalsIgnoreCase("li") // Is sometimes minimized