search

farinspace / wpalchemy

Thin framework for wordpress
http://wpalchemy.com/
Other
416 stars 110 forks source link

Add online phpDoc documentation #74

Closed aendra-rininsland closed 8 years ago

aendra-rininsland commented 11 years ago

First off — this is the second time I've used your class and I like it more and more each time. Seriously good work.

Secondly — the farinspace website is really the sole source of documentation about your class. There's the massive monolithic data dump, the data storage post, the post on filtering and repeating and the install and setup post, in addition to any I may have missed. This is great if you're wanting a high-level overview, less great if you're wanting fast and to-the-point info on what anything does.

An example: try and find some documentation for what exactly the the_checkbox_state() method does. I'm still not entirely clear on what it does, and short of running it through a debugger (Which I think I ended up having to do the first time I used WP_Alchemy), there's no real way of figuring that out.

(Again, that's unless I'm just web illiterate/blind and am just missing where you've documented that method — apologies if so!)

My suggestions:

  1. Start using GitHub's wiki for in-depth functional documentation.
  2. Continue using farinspace.com as a high-level overview and example site.
  3. You already have great comments in your source. To go back to my example, this line in MetaBox.php tells me exactly what the_checkbox_state() does. All you really need to do is convert them to Doxygen format (They're not far off) and run them through the Doxygen converter.

Let me know if you want any help with this, would love to contribute any way I can.

Thanks!

farinspace commented 11 years ago

I very much like the idea, if you have the time I will definitely make you a contributor and give you access to the github repo to help with the wiki documentation. Again, thank you for the suggestions.

aendra-rininsland commented 11 years ago

Cool, sounds good! I'll fork now and make some pull requests once I've tidied up the comments later on this week.

aendra-rininsland commented 11 years ago

Looking through your documentation, it seems your syntax is much closer to phpDoc than it is to Doxygen. If it's all the same to you, I'd rather use phpDocumentor2 to generate these -- not only does it create prettier output, but I also won't have to rewrite all your comments!

If you're okay with that, let me know and I'll try to post some generated output later today.

Edit: Seems your code is geared toward PHP4's OOP implementation, i.e., not using the public/protected/private keywords, while phpDoc2 is best when methods/properties are clearly delineated. Note the minimum version of PHP compatible with the current release of WordPress is 5.2.4, which was updated from 4.3 in WordPress 3.2. I can do one of the following:

  1. Use phpDoc2 as-is, with non-functioning fields for the property/method scopes.
  2. Update the code to PHP5 standards.
  3. Convert everything to Doxygen.
  4. Use phpDoc v1 (Done, see below).

Let me know whichever you'd prefer!

Edit2: Using the least-ugly phpDoc v1 theme I could find, I've uploaded the generated documentation to here. If happy with that, let me know and I'll open a pull request. If not and are wanting to update the codebase to PHP5 (Thus requiring a major version increment, if using SemVer), let me know and I can help with that.

farinspace commented 11 years ago

Ideally I want everything in github wiki, so that I and others can update, and really everything should be pretty simply formatted (markdown) .. I am assuming that these documenters could transfer their output to github?

I would plan on converting the codebase to PHP5 (I can do that pretty quickly I think, on a weekend), so going with phpDoc2 would be ok with me.

farinspace commented 11 years ago

oh, thanks for the semver link :-)

aendra-rininsland commented 11 years ago

Quite agreed re: putting in a wiki, this is only an intermediate stage in processing the data. Eventually I'll use something like phpdoc-md to generate the .md files for the wiki. For some reason, .md isn't super widely supported as an output format for documentation generators yet.

That all said, rad about moving to PHP5; really, it's not much more involved than changing "var" to public/protected/private and updating your comments to reflect that. I can even open a new issue and help contribute to that if you'd like, it'd be a pretty quick series of changes.

farinspace commented 8 years ago

going through all the issues .. marking most as old/closed, I will likely leave current code on a 1.x branch and only do updates/fixes .. perhaps starting a 2.x branch with best practices