Hi all-
There are two main ways to do examples, one includes the output
within the example itself while another uses <screen> shortly
after. I prefer putting the output inline as the user can
take the expected output home with them (in their cut-n-paste).
Also, if we ever create that index of all examples then both code
and output will be included without much thought. Here's what
I mean:
--------------------------------
Simple examples:
--------------------------------
<?php
$var = ucfirst('hello');
print $var; // Hello
print $var; // outputs: Hello
?>
In the above I see no need to write "outputs:" in the comment
and prefer the first. I certainly hope a user knows what
print or echo does. The coding-standards shows outputs:
in the example. I vote that is unneeded except when in /* */
like so:
--------------------------------
More 'complex' examples:
--------------------------------
<?php
$arr = explode('|', 'a|b|c|d|e|f|g');
print_r($arr);
/* Outputs:
Array
(
[0] => a
[1] => b
[2] => c
[3] => d
[4] => e
[5] => f
[6] => g
)
*/
?>
The other method suggests using <screen> for output in a new <para>
after the example. This is fine but I prefer the inline method and
would like to hear other peoples opinions on this matter. The
coding-standards RFC suggests to use <screen>, I vote this is
changed. Although there are times when using <screen> is appropriate,
like for command line operations, so in those occasions use <screen>.
Regards,
Philip
re: phpdoc/RFC/codeing-standards
--
PHP Documentation Mailing List (http://www.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php
