A DESCRIPTION OF THE REQUEST :
Hello,

My name is Taiyue Liu. Me (a masters student) and Edmund Wong (a PhD student) at University of Waterloo are conducting a research on automatic comment generation. We included JDK as an open source software in the evaluation (thanks for making your code open source!) of our research. Our tool generated the several comments for your project's source code, which are mined from open source projects in GitHub. We would like to report these comments to you, the developer, and learn about their quality. If you think you are not the right person to contact for questions about the source code, feel free to redirect me. In any case that you wish not to participate in this study, that is fine too.

If you have a moment, would you mind to check if the attached code comments are applicable to JDK’s source code, and rank them based on the following scale (on a commit basis criteria)?

The code comment is:
[1] accurate, adequate, concise and useful at describing the source code. (committable)
[2] not accurate, adequate, concise, or useful, at describing the source code but can be fixed with minor modifications. (committable but require fixes)
[3] not accurate, adequate, concise, or useful at describing the source code. (not committable)

In this email we included:
1) the generated comments ("commentsJDK.txt"), and
2) the corresponding source code file for your convenience.
1-CopyOnWriteArrayList.java
2-Canonicalizer11.java
3-Canonicalizer20010315.java
4-NameSpaceSymbTable.java
5-FileCacheImageInputStream.java
6-Formatter.java
7-GTKColorChooserPanel.java
8-GTKColorChooserPanel.java
9-ForkJoinPool.java
10-XMLSignatureInput.java
11-CharsetEncoder.java
12-XIncludeHandler.java
13-LinkedTransferQueue.java

Any information about you will be kept confidential. Once again, the goal of this research is to evaluate these generated code comments' quality and we would appreciate it if you, the developer, can help us on the evaluation.

If you desire to know more about our research project, reply to this email and I will get back to you.

Thanks,
Taiyue Liu, MASc,
University of Waterloo

Edmund Wong, PhD,
University of Waterloo

JUSTIFICATION :
Comment #1:

/home/edmund/evaluate_projects/JDK/java/util/concurrent/CopyOnWriteArrayList.java: 838-851
[COMMENT #1] Write out element count, and any hidden stuff

     /**
      * Saves the state of the list to a stream (that is, serializes it).
      *
      * @serialData The length of the array backing the list is emitted
      * (int), followed by all of its elements (each an Object)
      * in the proper order.
      * @param s the stream
      */
     private void writeObject(java.io.ObjectOutputStream s)
         throws java.io.IOException{
 
****** COMMENT #1 ******
         s.defaultWriteObject();
 
         Object[] elements = getArray();


# Rating on this comment
# 1: accurate, adequate, concise and useful at describing the source code. (committable)
# 2: not accurate, adequate, concise, or useful, at describing the source code but can be fixed with minor modifications.
# (committable but require fixes)
# 3: not accurate, adequate, concise, or useful at describing the source code. (not committable)
# (Fill in after the keyword: 1, 2 or 3)
CLASSIFICATION:

————————————
Comment #2:

/home/edmund/evaluate_projects/JDK/com/sun/org/apache/xml/internal/security/c14n/implementations/Canonicalizer11.java: 241-248
[COMMENT #1] New definition check if it is relative

            if (n != null) {
                // Render the ns definition
                result.add(n);
                if (C14nHelper.namespaceIsRelative(N)) {
****** COMMENT #1 ******
                    Object exArgs[] = {E.getTagName(), NName, N.getNodeValue()};
                    throw new CanonicalizationException(
                        "c14n.Canonicalizer.RelativeNamespace", exArgs);
                }
            }


# Rating on this comment
# 1: accurate, adequate, concise and useful at describing the source code. (committable)
# 2: not accurate, adequate, concise, or useful, at describing the source code but can be fixed with minor modifications.
# (committable but require fixes)
# 3: not accurate, adequate, concise, or useful at describing the source code. (not committable)
# (Fill in after the keyword: 1, 2 or 3)
CLASSIFICATION:

————————————
Comment #3:
/home/edmund/evaluate_projects/JDK/com/sun/org/apache/xml/internal/security/c14n/implementations/Canonicalizer20010315.java: 199-206
[COMMENT #1] New definition check if it is relative

          if (n!=null) {
                 //Render the ns definition
             result.add(n);
             if (C14nHelper.namespaceIsRelative(N)) {
****** COMMENT #1 ******
                Object exArgs[] = { E.getTagName(), NName, N.getNodeValue() };
                throw new CanonicalizationException(
                   "c14n.Canonicalizer.RelativeNamespace", exArgs);
             }
          }


# Rating on this comment
# 1: accurate, adequate, concise and useful at describing the source code. (committable)
# 2: not accurate, adequate, concise, or useful, at describing the source code but can be fixed with minor modifications.
# (committable but require fixes)
# 3: not accurate, adequate, concise, or useful at describing the source code. (not committable)
# (Fill in after the keyword: 1, 2 or 3)
CLASSIFICATION:

————————————
Comment #4:

/home/edmund/evaluate_projects/JDK/com/sun/org/apache/xml/internal/security/c14n/implementations/NameSpaceSymbTable.java: 231-233
[COMMENT #1] Mark this entry as render.

        if ((ob!=null) && uri.equals(ob.uri)) {
            if (!ob.rendered) {
****** COMMENT #1 ******
                ob=(NameSpaceSymbEntry) ob.clone();
                needsClone();
                symb.put(prefix,ob);
                ob.lastrendered=uri;
                ob.rendered=true;
                return ob.n;
            }
            return null;
        }


# Rating on this comment
# 1: accurate, adequate, concise and useful at describing the source code. (committable)
# 2: not accurate, adequate, concise, or useful, at describing the source code but can be fixed with minor modifications.
# (committable but require fixes)
# 3: not accurate, adequate, concise, or useful at describing the source code. (not committable)
# (Fill in after the keyword: 1, 2 or 3)
CLASSIFICATION:

————————————
Comment #5:

/home/edmund/evaluate_projects/JDK/javax/imageio/stream/FileCacheImageInputStream.java: 285-287
[COMMENT #1] Remove temporary file.

        public synchronized void dispose() {
            if (cache != null) {
                try {
                    cache.close();
                } catch (IOException e) {
                } finally {
                    cache = null;
                }
            }
****** COMMENT #1 ******
            if (cacheFile != null) {
                cacheFile.delete();
                cacheFile = null;
            }
            // Note: Explicit removal of the stream from the StreamCloser
            // queue is not mandatory in this case, as it will be removed
            // automatically by GC shortly after this method is called.
        }


# Rating on this comment
# 1: accurate, adequate, concise and useful at describing the source code. (committable)
# 2: not accurate, adequate, concise, or useful, at describing the source code but can be fixed with minor modifications.
# (committable but require fixes)
# 3: not accurate, adequate, concise, or useful at describing the source code. (not committable)
# (Fill in after the keyword: 1, 2 or 3)
CLASSIFICATION:

————————————
Comment #6:

/home/edmund/evaluate_projects/JDK/java/util/logging/Formatter.java: 92-118
[COMMENT #1] Look for a resource bundle
 
    public synchronized String formatMessage(LogRecord record) {
        String format = record.getMessage();
****** COMMENT #1 ******
        java.util.ResourceBundle catalog = record.getResourceBundle();
        if (catalog != null) {
            try {
                format = catalog.getString(record.getMessage());
            } catch (java.util.MissingResourceException ex) {
                // Drop through. Use record message as format
                format = record.getMessage();
            }
        }
        // Do the formatting.
        try {
            Object parameters[] = record.getParameters();
            if (parameters == null || parameters.length == 0) {
                // No parameters. Just return format string.
                return format;
            }
            // Is it a java.text style format?
            // Ideally we could match with
            // Pattern.compile("\\{\\d").matcher(format).find())
            // However the cost is 14% higher, so we cheaply check for
            // 1 of the first 4 parameters
            if (format.indexOf("{0") >= 0 || format.indexOf("{1") >=0 ||
                        format.indexOf("{2") >=0|| format.indexOf("{3") >=0) {
                return java.text.MessageFormat.format(format, parameters);
            }
            return format;

        } catch (Exception ex) {
            // Formatting failed: use localized format string.
            return format;
        }
    }


# Rating on this comment
# 1: accurate, adequate, concise and useful at describing the source code. (committable)
# 2: not accurate, adequate, concise, or useful, at describing the source code but can be fixed with minor modifications.
# (committable but require fixes)
# 3: not accurate, adequate, concise, or useful at describing the source code. (not committable)
# (Fill in after the keyword: 1, 2 or 3)
CLASSIFICATION:

————————————
Comment #7:

/home/edmund/evaluate_projects/JDK/com/sun/java/swing/plaf/gtk/GTKColorChooserPanel.java: 138-142
[COMMENT #1] try parsing as a number

    /**
     * Character to underline that represents the mnemonic.
     */
    public int getDisplayedMnemonicIndex() {
        String m = (String)UIManager.get(
                           "GTKColorChooserPanel.displayedMnemonicIndex");

        if (m != null) {
****** COMMENT #1 ******
            try {
                int value = Integer.parseInt(m);

                return value;
            } catch (NumberFormatException nfe) {}
        }
        return -1;
    }


# Rating on this comment
# 1: accurate, adequate, concise and useful at describing the source code. (committable)
# 2: not accurate, adequate, concise, or useful, at describing the source code but can be fixed with minor modifications.
# (committable but require fixes)
# 3: not accurate, adequate, concise, or useful at describing the source code. (not committable)
# (Fill in after the keyword: 1, 2 or 3)
CLASSIFICATION:

————————————
Comment #8:

/home/edmund/evaluate_projects/JDK/com/sun/java/swing/plaf/gtk/GTKColorChooserPanel.java: 121-125
[COMMENT #1] try parsing as a number

    public int getMnemonic() {
        String m = (String)UIManager.get("GTKColorChooserPanel.mnemonic");

        if (m != null) {
****** COMMENT #1 ******
            try {
                int value = Integer.parseInt(m);

                return value;
            } catch (NumberFormatException nfe) {}
        }
        return -1;
    }


# Rating on this comment
# 1: accurate, adequate, concise and useful at describing the source code. (committable)
# 2: not accurate, adequate, concise, or useful, at describing the source code but can be fixed with minor modifications.
# (committable but require fixes)
# 3: not accurate, adequate, concise, or useful at describing the source code. (not committable)
# (Fill in after the keyword: 1, 2 or 3)
CLASSIFICATION:

————————————
Comment #9:

/home/edmund/evaluate_projects/JDK/java/util/concurrent/ForkJoinPool.java: 1272-1276
[COMMENT #1] Signal anyone waiting, so they see the close flag

        if ((short)(c >>> TC_SHIFT) == -parallelism) { // signal when 0 workers
            final ReentrantLock lock = this.submissionLock;
****** COMMENT #1 ******
            lock.lock();
            try {
                termination.signalAll();
            } finally {
                lock.unlock();
            }
        }
        return true;


# Rating on this comment
# 1: accurate, adequate, concise and useful at describing the source code. (committable)
# 2: not accurate, adequate, concise, or useful, at describing the source code but can be fixed with minor modifications.
# (committable but require fixes)
# 3: not accurate, adequate, concise, or useful at describing the source code. (not committable)
# (Fill in after the keyword: 1, 2 or 3)
CLASSIFICATION:

————————————
Comment #10:

/home/edmund/evaluate_projects/JDK/com/sun/org/apache/xml/internal/security/signature/XMLSignatureInput.java: 602-604
[COMMENT #1] Initiate DocumentBuilderFactory

    void convertToNodes() throws CanonicalizationException,
        ParserConfigurationException, IOException, SAXException {
****** COMMENT #1 ******
        DocumentBuilderFactory dfactory = DocumentBuilderFactory.newInstance();
        dfactory.setValidating(false);
        dfactory.setNamespaceAware(true);
        dfactory.setFeature(XMLConstants.FEATURE_SECURE_PROCESSING,
                            Boolean.TRUE);
        DocumentBuilder db = dfactory.newDocumentBuilder();


# Rating on this comment
# 1: accurate, adequate, concise and useful at describing the source code. (committable)
# 2: not accurate, adequate, concise, or useful, at describing the source code but can be fixed with minor modifications.
# (committable but require fixes)
# 3: not accurate, adequate, concise, or useful at describing the source code. (not committable)
# (Fill in after the keyword: 1, 2 or 3)
CLASSIFICATION:

————————————
Comment #11:

/home/edmund/evaluate_projects/JDK/java/nio/charset/CharsetEncoder.java: 792-795
[COMMENT #1] copy the old buffer into this new buffer
[COMMENT #2] and make the new buffer be the real thing
 
        for (;;) {
            CoderResult cr = in.hasRemaining() ?
                encode(in, out, true) : CoderResult.UNDERFLOW;
            if (cr.isUnderflow())
                cr = flush(out);

            if (cr.isUnderflow())
                break;
            if (cr.isOverflow()) {
                n = 2*n + 1; // Ensure progress; n might be 0!
                ByteBuffer o = ByteBuffer.allocate(n);
****** COMMENT #1 ******
                out.flip();
                o.put(out);
****** COMMENT #2 ******
                out = o;
                continue;
            }
            cr.throwException();
        }


# Rating on [COMMENT #1]
# 1: accurate, adequate, concise and useful at describing the source code. (committable)
# 2: not accurate, adequate, concise, or useful, at describing the source code but can be fixed with minor modifications.
# (committable but require fixes)
# 3: not accurate, adequate, concise, or useful at describing the source code. (not committable)
# (Fill in after the keyword: 1, 2 or 3)
CLASSIFICATION:

# Rating on [COMMENT #2]
# 1: accurate, adequate, concise and useful at describing the source code. (committable)
# 2: not accurate, adequate, concise, or useful, at describing the source code but can be fixed with minor modifications.
# (committable but require fixes)
# 3: not accurate, adequate, concise, or useful at describing the source code. (not committable)
# (Fill in after the keyword: 1, 2 or 3)
CLASSIFICATION:

————————————

Comment #12:

/home/edmund/evaluate_projects/JDK/com/sun/org/apache/xerces/internal/xinclude/XIncludeHandler.java: 2185-2189
[COMMENT #1] Append the path

                    final StringBuilder buffer = new StringBuilder();

****** COMMENT #1 ******
                    if (literalPath != null) {
                        buffer.append(literalPath);
                    }
                    if (literalQuery != null) {
                        buffer.append('?');
                        buffer.append(literalQuery);
                    }
                    if (literalFragment != null) {
                        buffer.append('#');
                        buffer.append(literalFragment);
                    }
                    return buffer.toString();


# Rating on this comment
# 1: accurate, adequate, concise and useful at describing the source code. (committable)
# 2: not accurate, adequate, concise, or useful, at describing the source code but can be fixed with minor modifications.
# (committable but require fixes)
# 3: not accurate, adequate, concise, or useful at describing the source code. (not committable)
# (Fill in after the keyword: 1, 2 or 3)
CLASSIFICATION:

————————————

Comment #13:

/home/edmund/evaluate_projects/JDK/java/util/concurrent/LinkedTransferQueue.java: 1322-1325
[COMMENT #1] Read in all elements and place in queue

    private void readObject(java.io.ObjectInputStream s)
        throws java.io.IOException, ClassNotFoundException {
        s.defaultReadObject();
****** COMMENT #1 ******
        for (;;) {
            @SuppressWarnings("unchecked") E item = (E) s.readObject();
            if (item == null)
                break;
            else
                offer(item);
        }
    }


# Rating on this comment
# 1: accurate, adequate, concise and useful at describing the source code. (committable)
# 2: not accurate, adequate, concise, or useful, at describing the source code but can be fixed with minor modifications.
# (committable but require fixes)
# 3: not accurate, adequate, concise, or useful at describing the source code. (not committable)
# (Fill in after the keyword: 1, 2 or 3)
CLASSIFICATION:

————————————