You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@harmony.apache.org by "Svetlana Konovalova (JIRA)" <ji...@apache.org> on 2007/03/02 12:06:50 UTC
[jira] Commented: (HARMONY-3284) [drlvm][doc] scarce comments in OS
portability layer external interface headers
[ 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.