harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Nadya Morozova (JIRA)" <j...@apache.org>
Subject [jira] Commented: (HARMONY-3284) [drlvm][doc] scarce comments in OS portability layer external interface headers
Date Mon, 25 Jun 2007 11:47:26 GMT

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

Nadya Morozova commented on HARMONY-3284:
-----------------------------------------

a couple of comments on questions from Alexei:

1 - ok, the intention was presumably to make the phrase shorter; suggest that we stick with
the original, "of" > "for" change is not recommended

2 - we've talked about it : if you have a non-Doxygen comment, Doxygen does not parse it so
when opening a Source view of the parsed file and expect to get a clean version, you see the
disclaimer; on the other hand, if you format the disclaimer so that Doxygen can digest it,
the comment disappears from the source view but is not attached to any code entity; using
normal Doxygen comment notation for disclaimers has been a common practice for quite a while
on Harmony :)

3 - about incorrect wording - i disagree with Alexei; the phrase "Initializes a component
manager if it does not exist. " can only be interpreted as it reads - if there has been no
component manager, it is created; the new version of the phrase is shorter and does not repeat
"component manager" two times

3 - about compound nouns - indeed, the hyphen is widely used and helps avoid ambiguity; a
quote from a well-known and respected book on technical writing Microsoft Manual of Style
for Technical Publications: "  Hyphenate two or more words that precede and modify a noun
as a unit if confusion might otherwise result. 
           Use memory-resident program, not TSR, in content for home users and information
workers.
           Some programs have dialog box-type options for frequently used operations.
           Other examples include items such as "arguments, command line" and "command-line
arguments."
i don't think this is a discussion of English grammar, but if you have more questions, i'd
be happy to help and consult. Really :) 

4.  Because we define a specific parameter, it passes the name of a specific function, and
everything specific is definite - hence, use a definite article :) If you said "an initializer
function", you'd mean any, does not matter which -but it does, it's code right there.

6. yes, we should probably run a check for dos2unix and tabs-to-spaces fixes before supplying
any patch

7. i haven't found differences in wording, so i presume, the change is done to limit comment-line
length to 80 characters. Sveta, correct me if you had some other fix in mind.

8. i guess it's for unification purposes; we don't usually indent the first comment line;
this is not a strict rule, but whichever style you choose, please follow through the whole
file. comments that are formatted inconsistently should be brought to a unified manner. 

Alexei,
please let me know if you have more questions. What should we do with the patch - once you're
satisfied with its quality?
thanks,
looking forward to your reply, Nadya

> [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.


Mime
View raw message