Mailing-List: contact commits-help@harmony.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@harmony.apache.org
Message-ID: <11731702.1174480832537.JavaMail.jira@brutus>
Date: Wed, 21 Mar 2007 05:40:32 -0700 (PDT)
From: "Nadya Morozova (JIRA)" <jira@apache.org>
To: commits@harmony.apache.org
Subject: [jira] Commented: (HARMONY-3180) [drlvm][doc] Improved portlib docs
In-Reply-To: <23013734.1171461665533.JavaMail.jira@brutus>
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: 7bit


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

Nadya Morozova commented on HARMONY-3180:
-----------------------------------------

Some specific suggestions to make the improved documentation near-perfect. I've grouped the comments by entity type. you can also find it useful to read the log file that Doxygen produces, all errors are stored there.

Defines:
- not all documented
- described in different ways; suggest using parallel constructions (one of the following, not both):
/** Enables read access to committed memory region */ >>> this is a verb phrase
#define PORT_VMEM_MODE_EXECUTE 0x4
/** System default page size */    >>> this is a noun phrase
#define PORT_VMEM_PAGESIZE_DEFAULT 0

Modules:
- not all documented. please add at least a short description of each module to say why it's necessary. some modules, such as Memory protection flags, are not defined so it's not easy to guess why the module is needed :)

Variables:
- not defined, should be

Typedefs:
- not all defined; undocumented: port_disassembler_t

Functions:
- not all parameters have the type specified; please add all types for consistency
- over 10 errors reported by Doxygen when the documented param was not found in function body and vice versa; please double-check that all function descriptions have the right set of parameters documented
- use consistent formatting of parameters: add a dash (-) between the param name[type] and definition; start definition at a small letter, no punctuation at the end of line

> [drlvm][doc] Improved portlib docs
> ----------------------------------
>
>                 Key: HARMONY-3180
>                 URL: https://issues.apache.org/jira/browse/HARMONY-3180
>             Project: Harmony
>          Issue Type: Improvement
>          Components: DRLVM, Website/Documentation
>            Reporter: Alexey Varlamov
>         Assigned To: Nadya Morozova
>            Priority: Minor
>         Attachments: port_doc.diff
>
>
> Fixed & extended doxygen comments in portlib headers;
> Fixed mainpage (it had copy-pasted * 5 content);
> Fixed paths and config for doxygen.

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