Comments on: Documenting the Easy Functions First http://jacobsantos.com/2008/general/documenting-the-easy-functions-first/ Rumblings, rants, essays, stories by Jacob Santos about Web Site Development, Persistent Browser-Based Games, personal journal, and Programming. Mon, 21 May 2012 13:04:07 +0000 hourly 1 http://wordpress.org/?v=3.3-aortic-dissection By: Jacob Santos http://jacobsantos.com/2008/general/documenting-the-easy-functions-first/comment-page-1/#comment-33226 Jacob Santos Thu, 26 Jun 2008 00:00:52 +0000 http://www.santosj.name/?p=585#comment-33226 I think it looks good, except that the "function_name() -" standard has been removed since it doesn't look right in phpdocumentor and phpxref sites. I wouldn't worry about critique, if something is wrong, someone will come along and fix it. I think it looks good, except that the “function_name() -” standard has been removed since it doesn’t look right in phpdocumentor and phpxref sites.

I wouldn’t worry about critique, if something is wrong, someone will come along and fix it.

]]> By: Scott http://jacobsantos.com/2008/general/documenting-the-easy-functions-first/comment-page-1/#comment-33225 Scott Tue, 24 Jun 2008 22:07:05 +0000 http://www.santosj.name/?p=585#comment-33225 Hey, I've kinda jumped in and had a go on formatting.php, expanding on your diff from trac. I've only done the first few functions at the moment but I was wondering if you'd mind checking them and pointing out anything I forgot or could've done better. The diff is <a href="http://www.scott-h.com/formatting.diff" rel="nofollow">here</a>. Cheers. Hey, I’ve kinda jumped in and had a go on formatting.php, expanding on your diff from trac. I’ve only done the first few functions at the moment but I was wondering if you’d mind checking them and pointing out anything I forgot or could’ve done better. The diff is here.

Cheers.

]]> By: Jacob Santos http://jacobsantos.com/2008/general/documenting-the-easy-functions-first/comment-page-1/#comment-33220 Jacob Santos Mon, 23 Jun 2008 01:55:35 +0000 http://www.santosj.name/?p=585#comment-33220 Also, if you document an entire file, then add your name to the list on <a href="http://codex.wordpress.org/Inline_Documentation#Inline_Documentation_Effort_Contributors" rel="nofollow">the list of contributors</a> for the inline documentation effort. Also, if you document an entire file, then add your name to the list on the list of contributors for the inline documentation effort.

]]> By: Jacob Santos http://jacobsantos.com/2008/general/documenting-the-easy-functions-first/comment-page-1/#comment-33219 Jacob Santos Mon, 23 Jun 2008 01:03:21 +0000 http://www.santosj.name/?p=585#comment-33219 Well, I'm having difficult finding time for post.php, which much of the inline documentation is inaccurate, which is worse than not having any. Function.php has half of the functions documented and is arguably the most used functions in WordPress besides formatting.php, which probably is the most used or close second. I jump around a lot, so I'm not sure what I'll be working on. My advice is always, if you see a function that you've discovered the meaning behind, then write documentation for it and apply a patch to http://trac.wordpress.org/ticket/7038 or if you document an entire file, search for a ticket for that file or if one doesn't exist then create one for it. I've been devoting about an hour each Saturday and Sunday to completing the inline documentation. I plan on completing the script loader.php and shortcodes.php files today. I also want to revisit some of the functions in post.php and try to fix the documentation for some of the functions. I'm probably not going to revisit functions.php or formatting.php until post.php is completed. Well, I’m having difficult finding time for post.php, which much of the inline documentation is inaccurate, which is worse than not having any.

Function.php has half of the functions documented and is arguably the most used functions in WordPress besides formatting.php, which probably is the most used or close second.

I jump around a lot, so I’m not sure what I’ll be working on. My advice is always, if you see a function that you’ve discovered the meaning behind, then write documentation for it and apply a patch to http://trac.wordpress.org/ticket/7038 or if you document an entire file, search for a ticket for that file or if one doesn’t exist then create one for it.

I’ve been devoting about an hour each Saturday and Sunday to completing the inline documentation. I plan on completing the script loader.php and shortcodes.php files today. I also want to revisit some of the functions in post.php and try to fix the documentation for some of the functions. I’m probably not going to revisit functions.php or formatting.php until post.php is completed.

]]> By: Scott http://jacobsantos.com/2008/general/documenting-the-easy-functions-first/comment-page-1/#comment-33218 Scott Sun, 22 Jun 2008 21:21:54 +0000 http://www.santosj.name/?p=585#comment-33218 I applaud your efforts. As a developer coming to wordpress interested in how it works, I was amazed at the lack of documentation in the code. I'm still getting my bearings but if you've got anything specific that you'd like help on, feel free to ask. I can't think of a better way of learning the code than by documenting it. I applaud your efforts. As a developer coming to wordpress interested in how it works, I was amazed at the lack of documentation in the code. I’m still getting my bearings but if you’ve got anything specific that you’d like help on, feel free to ask. I can’t think of a better way of learning the code than by documenting it.

]]>