(2008-06-30, 10:09 PM)Jeff Wrote: [ -> ]You make it seem like the effort put into PHPdoc is useless. If PHPdoc isn't necessary, then why bother doing it the first place? You could just always type a one line comment.
Pretty much. There's millions of projects which are probably not much more useful than for novelty purposes.
(2008-06-30, 10:09 PM)Jeff Wrote: [ -> ]I think there's a point of it and for some people, it's useful. (like me)
Well, if you find it useful, then I can't say anything.
(2008-07-01, 12:28 AM)labrocca Wrote: [ -> ]Sometimes you forget how the function is named but you know part of it. Like the other day I did getuser() instead of get_user()...I checked quickly and saw the error. For me the phpdoc is faster than opening up the various function php pages...it's not like they are in one file. Also phpdoc is a good reference to see overall the various functions.
I'd just type the query out in full then:
$user = $db->fetch_array($db->simple_select("users", "*", "uid=".$uid));
Takes a few seconds - much faster than going through any reference.
Or, if "getuser" didn't work, use some intuition and try "get_user" or other variants. Of course, if you totally didn't know the name, I don't see how a function reference is going to help.
In MyBB, all the general purpose functions are located in inc/functions.php so you don't need to search through multiple PHP files. If the function isn't in functions.php, then you probably don't need to use it.
In your example, look at the functions list for functions.php, and you would've quickly seen "get_user".
(2008-07-01, 12:28 AM)labrocca Wrote: [ -> ]If you are comfortable in your own method that's great. But not everyone needs to do things your way. imho...whatever works ...works.
True, but most people like to use unnecessary "fancy" methods which really aren't more convenient.
(2008-07-01, 12:28 AM)labrocca Wrote: [ -> ]I disagree. If you have a reference bookmarked it's going to be a lot faster than checking multiple PHP files.
Bookmark PHP files?
(2008-07-01, 12:28 AM)labrocca Wrote: [ -> ]http://www.mybbcentral.com/docs/
That's one page and it's incredibly quick reference. Plus it gives the variables used. The classes part can be handy as well. It's all good and all in one place.
The side panel only has like... 500 lines? Not to mention that MyBB is relatively small compared to some other scripts out there, where there'll probably be thousands of functions you'll never use.
How often have you used the function
draw_dots?
hello_activate?
myps_register_default? (that a MyBB function?)
IMO, automated documentation really isn't worthwhile. If documentation is done properly (manually), then it can, indeed, be a powerful tool.