Re: Module Documentation Style? (What it should be?)
| From: | Yasuo Ohgaki | Date: | Mon, 30 Apr 2001 16:29:22 +0000 |
| Subject: | Re: Module Documentation Style? (What it should be?) | ||
| References: | 1 | Groups: | php.doc |
| Request: | Send a blank email to phpdoc+get-969335164@lists.php.net to get a copy of this message | ||
Just for your reference, very 1st draft manual pages for the module is located
at
http://www.dd.iij4u.or.jp/~yohgaki/php/Manual_en/ref.jstring.html
(Due to storage size limit, I deleted most of pages that is not related to it)
There are mistakes descriptions, typo, etc. I'll fix them later. I need to know
if this style is acceptable or not. Thanks for your comments.
Regards,
--
Yasuo Ohgaki
""Yasuo Ohgaki"" <yohgaki@hotmail.com> wrote in message
news:9ck0gu$72h$1@toye.p.sourceforge.net...
> I thought it might be a good idea to ask before I finish making a new function
> reference.
>
> Almost all current PHP function references in PHP manual do not have separated
> description for function parameters/return value. (I understand why, it's in
> README in phpdoc CVS) Here is my question for you.
>
> Is it acceptable to have separated description for parameters and return value
> for a function? (For new function/module reference?)
>
> For example,
> --------------
> jstr_strimwidth
>
> (PHP 4 >= 4.0.6)
>
> jstr_strimwidth - Truncated string with specified display width
>
> Description
> string jstr_strimwidth(string str, int start, int width [, string trimmarker
[,
> string encoding]])
>
> Truncates string to specified display width.
>
> Parameter:
> str : String to be truncated
> start : Start position in number of characters from the beginning of string
> width : Displayed width
> trimmarker : String to add when string is truncated.
> encoding : Character code name. If encoding is not specified, internal
> character code is used.
>
> Return Value:
> Truncated string.
>
> Example:
> $str = jstr_strimwidth($str, 0, 40, "..>");
> -----------------
>
> Some functions set default value when parameter is set, and return current
> settings if parameter is omitted. Return values are differ depends on
parameter
> or what has been done in function. I thought it would be nice to users to have
a
> separated sub section (sub section like paragraph) for the module's function.
>
> Thanks for your reply.
>
> --
> Yasuo Ohgaki
>