Ticket #244 (new task)

Opened 8 years ago

Last modified 4 years ago

Coding guidelines and code documentation through phpDocumentor

Reported by: DarTar Owned by: unassigned
Priority: normal Milestone: blue-sky
Component: documentation Version: 1.1.6.2
Severity: normal Keywords: phpDoc api
Cc:

Description (last modified by BrianKoontz) (diff)

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.

Change History

  Changed 8 years ago by NilsLindenberg

  • type changed from defect to task

Some headers add to actions in [244].

  Changed 8 years ago by NilsLindenberg

[144] of course.

  Changed 8 years ago by DarTar

  Changed 8 years ago by DarTar

  • description modified (diff)

  Changed 8 years ago by NilsLindenberg

  Changed 8 years ago by NilsLindenberg

  Changed 8 years ago by NilsLindenberg

  Changed 7 years ago by NilsLindenberg

  Changed 7 years ago by DotMG

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

  Changed 7 years ago by DotMG

[263] : files.xml.php handler

  Changed 7 years ago by DarTar

  • component changed from unspecified to documentation
  • milestone changed from 1.1.7.2 to 1.1.7

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

  Changed 7 years ago by DarTar

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

  Changed 7 years ago by DarTar

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

  Changed 7 years ago by DarTar

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

  Changed 7 years ago by DarTar

  • description modified (diff)

  Changed 7 years ago by DarTar

  • description modified (diff)

  Changed 7 years ago by DarTar

  • description modified (diff)

  Changed 7 years ago by DarTar

[344] fixes typo/incorrect docblock description.

  Changed 7 years ago by anonymous

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

  Changed 7 years ago by DarTar

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

  Changed 7 years ago by DarTar

  • description modified (diff)
  • summary changed from Self-documenting code through phpDoc to Coding guidelines and code through phpDoc

  Changed 7 years ago by DarTar

  • keywords phpDoc api added
  • summary changed from Coding guidelines and code through phpDoc to Coding guidelines and code documentation through phpDocumentor

  Changed 7 years ago by DarTar

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

  Changed 7 years ago by BrianKoontz

  • description modified (diff)

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

  Changed 6 years ago by DotMG

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

Comments in source code should not appear in rendered HTML.

  Changed 6 years ago by DotMG

(In [1221]) refs #244

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

  Changed 5 years ago by DarTar

  • milestone changed from 1.2 to 1.3

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

follow-up: ↓ 29   Changed 5 years ago by 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?

in reply to: ↑ 28   Changed 5 years ago by 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.

  Changed 5 years ago by BrianKoontz

  • priority changed from high to normal

  Changed 5 years ago by 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.

  Changed 4 years ago by BrianKoontz

  • milestone changed from 1.3 to blue-sky
Note: See TracTickets for help on using tickets.