Coding guidelines and code documentation through phpDocumentor

[DarTar]

Since we are planning to use  phpDocumentor to automatically generate a  Wikka API documentation, all files, classes, functions and - where necessary - also variables and constants, should be documented trough the appropriate phpdoc comments. A basic guide on how to add phpDoc headers and comments can be found  here. If you are already familiar with phpDoc syntax and wish to help documenting Wikka code, you can:

• check out the latest version of undocumented code from the repository;
• add the relevant phpdoc description and tags;
• upload it as an attachment to this ticket.

We will review it, merge it with the code and be eternally grateful :)

Subtasks

• SVN keywords #261
• docbook tutorials #429
• cross-referencing #432

This ticket should also be used as a reference for works related to applying Wikka's  coding guidelines.

[NilsLindenberg]

Some headers add to actions in [244].

[NilsLindenberg]

[144] of course.

[DarTar]

[147]

[NilsLindenberg]

[155]

[NilsLindenberg]

[156]

[NilsLindenberg]

[158]

[NilsLindenberg]

[206]

[DotMG]

[214] : diff.php, revisions.php, history.php

[DotMG]

[263] : files.xml.php handler

[DarTar]

We should try to aim for a basic documentation already in 1.1.7

[DarTar]

[302] adds some preliminary instructions on how to correctly document language translation strings from a phpdoc point of view (see #340) .

[DarTar]

[303] [304] fix issues with the phpdoc header in the lang file - #340

[DarTar]

[318] updates copyright notice in the docblock for the core class.

[DarTar]

[344] fixes typo/incorrect docblock description.

[anonymous]

[409] minor changes to docblock and applying coding guidelines to wikka.php

[DarTar]

(In [415]) applying coding guidelines to the Wakka class (first step) refs #244

[DarTar]

(In [418]) Applying coding guidelines to the Wakka class (2nd step) refs #244

[BrianKoontz]

Modified description -- updated link to documentation how-to.

[DotMG]

(In [887]) refs #244, #562.

Comments in source code should not appear in rendered HTML.

[DotMG]

(In [1221]) refs #244

documentation through phpDocumentor (docblocks) for libs/Wakka.class.php

[DarTar]

Retargeting to 1.3. Code for this ticket may have already been committed to trunk, from which 1.3 will be branched. Consider backporting urgent issues to 1.2.X

[erlend_sh]

Is phpDocumenter still the best contender for this, scheduled for proper integration with workflow at some point? I just feel like there's bound to be a more solid solution out there somewhere by now.

- The last piece of update from this project is more than 1 1/2 old. - So far I haven't found a code commit more recent than from 2000; the project must be hosted somewhere else than SourceForge now I suppose - Their forum is a dead SF forum.

Surely better options could be found with just a little digging?

[BrianKoontz]

Replying to erlend_sh:

Is phpDocumenter still the best contender for this, scheduled for proper integration with workflow at some point? I just feel like there's bound to be a more solid solution out there somewhere by now. Surely better options could be found with just a little digging?

Given enough time and resources, all things are possible. Lacking one or both, prioritization of tasks become paramount. Right now, phpDocumenter is somewhat low on the priority list. However, if you know of some alternatives, please feel free to post them here so when one of us does get the time and/or resources to visit the issue, we'll be able to check out your leads.

[DarTar]

PhpDocumentor 1.4.3 was released in  September 2009. They have a slow release cycle, but to my knowledge it's by far the most solid code documenting solution for PHP.