Doc block guidelines

[nkkollaw]

I'm wondering, does it really make sense to add documentation to our functions, if they're barely a wrapper to the original ones?

Unless there are gotchas, I would just leave:

/**
 * @link http://php.net/manual/en/function.xxx.php
 */

If we change something apart from the name of the function itself, we could just add a note:

/**
 * @link http://php.net/manual/en/function.xxx.php
 *
 * NOTE: in Zubr, the $haystack argument is first, $needle last.
 */

What do you guys think? IMHO it's much cleaner, and this way one would actually read the comment and see what's going on. No point in documenting something that most people already know and is on php.net anyway...

[ddziaduch]

hm, good idea 👍

[nkkollaw]

@radmen ..?

[nkkollaw]

...it might also make sense to always have the "NOTE" part, so even if the function didn't change from the original:

/**
 * @link http://php.net/manual/en/function.xxx.php
 *
 * NOTE: no change
 */

[ddziaduch]

Ok, my proposal - @link tag for every function - but the functions with different order should use @param tag - @nkkollaw what about that?

[nkkollaw]

Yes, if functions have changes we have to document them with @param, @return if we return something different, etc.

I will create an example and put it in the CONTRIBUTING file.

[radmen]

I'd say that we should keep bare minimum:

• Short description - usually the first line from php.net (eg for strstr: Find the first occurrence of a string)
• @param
• @return
• @link to docs on php.net

(sorry for late response, I'm still on vacation till end of week)

[nkkollaw]

I'd say that we should keep bare minimum

I don't know if we have to document PHP's functions. I think it's more useful to describe what we change, since we expect our target to know what they're doing if they're using and feel the need for this kind of library.

Personally, I'm fine with @param etc. if they're already there (e.g., if adding them doesn't slow us down0, but the description I would along the lines of:

No change from original (see php.net/strstr)

or:

NOTE: we switched $haystack with $needle as per our guidlines

sorry for late response, I'm still on vacation till end of week

No problem!