Documentor

4 views
Skip to first unread message

Henrik Bechmann

unread,
Feb 9, 2011, 10:07:23 PM2/9/11
to simpl...@googlegroups.com
FYI I'm about to shift into php mode for a while (having reached a plateau with javascript browser work, eg a data explorer).

Looking at code documenters, I think I'll give doxygen a try (rather than phpdoc) since it's still a live project and has good reviews.

Comments welcome.

- Henrik

--
bechmann.ca

Christian Sciberras

unread,
Feb 10, 2011, 9:31:51 AM2/10/11
to simpl...@googlegroups.com
Hello Henrik,

Doxygen works over PHPDoc. PHPDoc is not "PHPDocumenter", it's the idea of writing special comments in code.
Then, you can use programs like doxygen or phpdocumenter to generate real documentation.
But personally, I would be happy in just seeing phpdoc comments.
Though, given enough PHPDoc comments, generating documentation is as simple as pressing a button.

Let me show you an example of PHPDoc:

<?php
  /**
   * Subtracts the value of $b from $a.
   * @param integer|float $a The value to subtract from.
   *
@param integer|float $b The value to subtract.
   * @return integer|float The subtracted value.
   * @example <code>
   *            echo substract(5, 1.5);
   *          </code>
   */

  function subtract($a, $b){
    return $a-$b;
  }
?>

The special comments /** ... */ tells use that it is a PHPDoc construct.
Words starting with @ are PHPDoc tags.
Here's a list of such tags:
param - Describes a function's parameter, must be preceded with the expected data type.
This could be basic types (boolean, integer, string), class names (MyObject, StdClass), a mix between types (integer|float) or any type (mixed).
After the data type, you must write the parameter's variable name. Finally, you can write a short description on the parameter.
return - Describes a function's return value. Must be preceded with a data type (see param tag), and an optional short description.
copyright - Some text describing the copyright holder. Usually used in the beginning of file or class.
author - Same as copyright, but describing the author (or a list of authors).
license - Same as copyright, but describing the code license.
version - Same as copyright, but describing the code version. Versioning can be anything, from version serials (1.3.4.6) to dates (10/05/2010).
link - Links this documentation to a URL (it's just a link like you would see in the notes section).
see - Same as link, but more specific.
example - Can include some usage code between code tags (see my example above).

Doxygen/phpdocumenter simply generates HTML and pages according to the stuff you write in PHPDoc comments.
So for example, the above @example clause is converted to:
<h3>Example</h3>
<pre class="php">
   
echo substract(5, 1.5);
</pre>

Cheers,
Chris.


--
You received this message because you are subscribed to the Google Groups "simplewiki" group.
To post to this group, send email to simpl...@googlegroups.com.
To unsubscribe from this group, send email to simplewiki+...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/simplewiki?hl=en.

Reply all
Reply to author
Forward
0 new messages