harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Svetlana Konovalova (JIRA)" <j...@apache.org>
Subject [jira] Commented: (HARMONY-3284) [drlvm][doc] scarce comments in OS portability layer external interface headers
Date Fri, 02 Mar 2007 11:06:50 GMT

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

Svetlana Konovalova commented on HARMONY-3284:
----------------------------------------------

Here are suggestions on how to improve code comments of the Thread manager component so that
Doxygen parses them correctly. 

GENERAL NOTE: I do respect the authors of all these headers and I do understand how proud
they are to see their names in the comments! :) But, since it's the open source, I'd like
to ask you to remove the authors' names from the files content. Thanks in advance and sorry
about that! 

OS portability layer
APR extension

port/include/apr_thread_ext.h
-Add detailed description 
-Add brief description [@file]
- Document functions

port/include/clog.h
-Add detailed description 
-Add brief description [@file]
- Document functions

port/include/cxxlog.h
-Add detailed description 
-Add brief description [@file]
- Add missing descriptions

port/include/lil.h
-Add detailed description 
-Add brief description [@file]
- Use appropriate formatting to make comments VISIBLE
- Add missing descriptions
- Use \ingroup, \defgroup (if applicable)
-Define parameters as [in]/[out]
-Use @return & @note
- Use <code> tags for code entities
- Avoid descriptions given in brackets. This info is perceived as redundant and excessive,
and is often omitted by the readers.

port/include/lil_code_generator.h
-Add detailed description 
-Add brief description [@file]
- Use appropriate formatting to make comments VISIBLE

port/include/lil_code_generator_utils.h
-Add detailed description 
-Add brief description [@file]
- Use appropriate formatting to make comments VISIBLE
- Add missing descriptions

port/include/log_macro.h
-Add detailed description
- Add one missing description

port/include/logger.h
-Add detailed description 
-Add brief description [@file]
- Add missing descriptions
- Use \ingroup, \defgroup (if applicable)

port/include/loggerstring.h
-Add detailed description 
-Add brief description [@file]
- Document functions 
- Use \ingroup, \defgroup (if applicable)

port/include/logparams.h
-Add detailed description 
-Add brief description [@file]
- Document functions 

port/include/m2n.h
-Add detailed description 
-Add brief description [@file]
- Use appropriate formatting to make comments VISIBLE
- Add missing descriptions
- Use <code> tags for code entities

port/include/platform_core_natives.h
-Add detailed description 
-Add brief description [@file]
- Document functions 

port/include/port_atomic.h
-Add detailed description 
-Add brief description [@file]
- Add missing descriptions
-Use @return & @note

port/include/port_disasm.h
-Add detailed description 
-Add brief description [@file]
- Add missing descriptions
- Use <code> tags for code entities
- Define parameters as  <in> / <out>

port/include/port_dso.h
-Add detailed description 
-Add brief description [@file]
- Add missing descriptions
- Use <code> tags for code entities
- Avoid descriptions given in brackets. This info is perceived as redundant and excessive,
and is often omitted by the readers.

port/include/port_filepath.h
-Add detailed description 
-Add brief description [@file]
- Add missing descriptions
- Use \ingroup, \defgroup (if applicable)

port/include/port_general.h
-Add detailed description 
-Add brief description [@file]
- Add missing descriptions

port/include/port_malloc.h
-Add detailed description 
-Add brief description [@file]
- Document functions 
- Use appropriate formatting

port/include/port_sysinfo.h
-Add detailed description 
-Add brief description [@file]
- Add missing descriptions

port/include/port_timer.h
-Add detailed description 
-Add brief description [@file]

port/include/port_vmem.h
-Add detailed description 
-Add brief description [@file]
- Add missing descriptions
- Use <code> tags for code entities
- Avoid descriptions given in brackets. This info is perceived as redundant and excessive,
and is often omitted by the readers.
-Define parameters as [in]/[out]

port/include/stack_iterator.h
-Use <code> tags for code entities

port/include/tl/allocator.h
-Add detailed description 
-Add brief description [@file]
- Use appropriate formatting to make comments VISIBLE

port/include/tl/list_mt.h
-Add detailed description 
-Add brief description [@file]
- Add missing descriptions

port/include/tl/memory_pool.h
-Add detailed description 
-Add brief description [@file]
- Add missing descriptions

port/include/tl/set_mt.h
-Add detailed description 
-Add brief description [@file]
- Add missing descriptions
- Use appropriate formatting

port/include/tl/set_mt.h
-Add detailed description 
-Add brief description [@file]
- Add missing descriptions

port/include/tl/vector.h
-Add detailed description 
-Add brief description [@file]
- Add missing descriptions

port/include/tl/vector_mt.h
-Add detailed description 
-Add brief description [@file]
- Add missing descriptions

port/src/encoder/dec_base.h
- Add missing descriptions
- Use appropriate formatting to split code and comments

port/src/encoder/enc_base.h
- Add missing descriptions
- Use <code> tags for code entities
- Define parameters as  <in> / <out>
-Add detailed description
- No need to put @brief in the beginning of function descriptions. Please remove.

port/src/encoder/enc_defs.h
-Add detailed description 
-Add brief description [@file]
- Add missing descriptions
- Use <code> tags for code entities
- Use appropriate formatting
-Use @return & @note

port/src/encoder/enc_prvt.h
-Add detailed description 
-Add brief description [@file]
- Add missing descriptions
- Use <code> tags for code entities
- Use appropriate formatting

port/src/encoder/encoder.h
- Add missing descriptions
- Use appropriate formatting
- Use \ingroup, \defgroup (if applicable)

port/src/lil/em64t/pim/include/lil_code_generator_em64t.h
-Add detailed description 
-Add brief description [@file]
- begin sentences with the capital letter.
- Use <code> tags for code entities

port/src/lil/ia32/pim/include/lil_code_generator_ia32.h   
-Add detailed description 
-Add brief description [@file]
- Document functions 

port/src/lil/ipf/pim/include/lil_code_generator_ipf.h   
-Add detailed description 
-Add brief description [@file]
- Document functions 
- Use appropriate formatting

port/src/lil/em64t/pim/m2n_em64t_internal.h 
-Add detailed description 
-Add brief description [@file]
- Add missing descriptions
- Use <code> tags for code entities
- Avoid descriptions given in brackets. This info is perceived as redundant and excessive,
and is often omitted by the readers.
-Define parameters as [in]/[out]

port/src/lil/ia32/pim/m2n_ia32_internal.h 
-Use appropriate formatting
-Add detailed description 
-Add brief description [@file]
- Add missing descriptions
- Use <code> tags for code entities

port/src/lil/ipf/pim/m2n_ipf_internal.h   
-Add detailed description 
-Add brief description [@file]
- Add missing descriptions
- Use <code> tags for code entities
- Use appropriate formatting to make comments VISIBLE

Component manager

include/open/compmgr.h
-Add detailed description (if applicable)
- Use <code> tags for code entities

include/component_manager.h
-Add detailed description 
-Add brief description [@file]


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