On Dec 29, 2007, at 2:22 PM, Ing. P.N.M. Tjon A Hen wrote:
Group,
Could you please review my mqseries extention documentation for
inclusion into
the php documentation.
Hello Philippe,
Here's a fairly verbose evaluation of your documents, and since this
is your first commit I'll be specific and picky but these are all
issues that as you work with the docs (and after the HOWTO update by
us is finished) will likely not happen.
The main concern here is with whitespace, as we have a strict policy
for whitespace in phpdoc. A quick summary:
- XML intention is one space (a few exceptions, see below)
- PHP code (in the examples) is four spaces as it follows the PEAR
coding standards
- The <!-- --> at end of each file should be the same, with no indenting
Some exceptions to the whitespace rule:
- <book xml:id is on a single line
- <![CDATA[ and ]]> are flush left, no indention
- <title>'s are always on a single line
- <member> in seealso are on a single line
- <refpurpose> also on a single line
It appears you used two or four spaces for the XML...
And a few non-WS issues that exist:
- Rename install.xml to configure.xml (mqseries.installation)
- Use &reftitle.install; inside configure.xml
- Rename configuration.xml to ini.xml (mqseries.configuration)
- If <refsect1 role="notes"> is empty, don't include it in the docs
- If a function has no return value, use &return.void; in the return
role
- Spelling issues, but I'm guessing you already found these
dance. :)
:)
If correct could I also get the right Karma to commit additional
changes to
the documentation. My cvs account for commiting code changes is
'philippe' .
Done. Please feel free to ask for another review before commit.
Regards,
Philip
