[jira] Commented: (HARMONY-3284) [drlvm][doc] scarce comments in OS portability layer external interface headers

["Alexei Fedotov (JIRA)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/HARMONY-3284?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12501171 ] 

Alexei Fedotov commented on HARMONY-3284:
-----------------------------------------

Thank you for your corrections. Adding my comments concerning the fixes.


1. What is the reason behind the following change?
/**
  * @ingroup Handles
- * The handle of the open component.
+ * The open component handle.
  */

Probably "of" can be replaced with "for" in my description, and there should be undefined articles. I intentionally put the long form here to outline that this is a handle.

2. What is rationale for the following change? License text is not a javadoc.

-/*
+/**
  *  Licensed to the Apache Software Foundation (ASF) under one or more
  *  contributor license agreements. See the NOTICE file distributed with

3. 
 /**
- * If no component manager exist, initializes a component manager.
- * Otherwise, increases a component manager reference count.
+ * Initializes a component manager if it does not exist.
+ * Otherwise, increases a component-manager reference count.

The sentence becomes incorrect. The system won't initialize a component manager as well if another one exists. I asked Nadya to provide a reference to the non-Intel documentation which prefixes "managers" with "-".

4.
  *
- * @param init_func - initializer function which provides a default
+ * @param init_func - the initializer function providing a default
  *                    and private interfaces for the component
An initializer function? Why we use "the" for non-defined term?

5. I'm ok with all following changes
/**
- * Decrement a reference counter and destroy a component manager if it
+ * Decrements a reference counter and destroys a component manager if it
  * becomes zero. The caller should ensure no cached handles will be used.
  *

6. It seems that the patch doesn't have correct line endings.
-/** 
+
+/**

7. What is the reason behind this change?
/**
  * @name Handles
- * Handles are opaque for an interface user. The user
- * operates with handles by means of interface functions.
+ * Handles are opaque for an interface user. The user operates with handles
+ * by means of interface functions.
  */

8. A format is changed to the incorrect one.
-    /**
-     * Returns a component version which is numbers separated with dots.
-     * Implementors must check a major version number for compatibility.
-     */
+/**
+ * Returns a component version where numbers are separated with dots.
+ * Implementors must check the major version number for compatibility.
+ */


> [drlvm][doc] scarce comments in OS portability layer external interface headers
> -------------------------------------------------------------------------------
>
>                 Key: HARMONY-3284
>                 URL: https://issues.apache.org/jira/browse/HARMONY-3284
>             Project: Harmony
>          Issue Type: Bug
>          Components: DRLVM
>            Reporter: Svetlana Konovalova
>         Attachments: 2include_headers.patch
>
>
> Many files lack ample and well-formatted comments; need to get easily readable, complete and useful reference for DRLVM Interface Reference and Java class library reference; the code commenting BKMs (http://wiki.apache.org/harmony/Code_Commenting) can be useful. Specific suggestions on improving Doxygen output are below.

-- 
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.