From bb6f3b9323d21867c2b2b8a82ea892d7e7ac2f01 Mon Sep 17 00:00:00 2001 From: moodler Date: Tue, 26 Apr 2005 12:50:18 +0000 Subject: [PATCH] Added information about phpdoc --- lang/en/docs/coding.html | 38 ++++++++++++++++++++++++++++---------- 1 file changed, 28 insertions(+), 10 deletions(-) diff --git a/lang/en/docs/coding.html b/lang/en/docs/coding.html index 072c25a6643..725371c9c48 100755 --- a/lang/en/docs/coding.html +++ b/lang/en/docs/coding.html @@ -132,17 +132,34 @@ GOOD: $assignments (for an array of objects)
$var = 'a very, very long string with a '.$single.' variable in it';
$var = "some $text with $many variables $within it";

-
  • Comments should use two or three slashes - and line up nicely with the code. -

    function forum_get_ratings_mean($postid, + + +

  • Comments should be added as much as is + practical, to explain the code flow and the purpose of functions and variables. +
      +
    • Every function (and class) should use the popular + phpDoc format. + This allows code documentation to be generated automatically.
      • +
    • Inline comments should use the // style, laid out neatly + so that it fits among the code and lines up with it.
      • +
    + +

    +/**
    + * The description should be first, with asterisks laid out exactly
    + * like this example. If you want to refer to a another function,
    + * do it like this: {@link clean_param()}. Then, add descriptions
    + * for each parameter as follows.
    + *
    + * @param int $postid The PHP type is followed by the variable name
    + * @param array $scale The PHP type is followed by the variable name
    + * @param array $ratings The PHP type is followed by the variable name
    + * @return mixed
    + */
    +function forum_get_ratings_mean($postid, $scale, $ratings=NULL) - {
    -     /// Return the mean rating of a post given - to the current user by others.
    - /// Scale is an array of possible ratings in the scale
    - /// Ratings is an optional simple array of actual ratings (just integers)
    -
    -         if (!$ratings) + {
     +     if (!$ratings) {
                $ratings = array();     // @@ -158,6 +175,7 @@ GOOD: $assignments (for an array of objects)
    {
    ....etc

    • +
  • Space should be used liberally - don't be afraid to spread things out a little to gain some clarity. Generally, there should be one space between brackets and normal statements, but no space between