Where's the best place for API examples

One thing I think would greatly improve the overall documentation (and hence usability) of Revo would be to build up the quantity & quality of API usage examples - particularly examples where real-world problems are solved. I recently used modParser->collectElementTags() for the first time, and found it quite handy - particularly the &$matches array that it returns. Since I hadn’t seen this used anywhere before, I thought it would be a good idea to supplement the documentation with an example of how to use the &$matches array in a plugin (I used it in an OnBeforeDocFormSave plugin to add output filters to certain tags).

The problem is, I couldn’t figure out where to add this example. The RTFM docs don’t have anything on modParser - splittingred explained to me that a decision was made to keep the API stuff in api.modx.com (and not have to manage it in two places). But the API docs are auto-generated by phpDocumentor - so they aren’t the place to add code examples.

Here’s my proposal: examples.modx.com. Use the same skeletal structure as the API docs - class-by-class, method-by-method. Developers could submit examples, and users could rate the examples with a star or thumbs-up/down system. And/or comments. The auto-generated API docs could be easily modified to add an ’examples’ link that would take you to the corresponding user-submitted examples for that particular method, and you could browse for the highest-rated examples.

Or this could be handled entirely by the user community I suppose. But it would be really nice to be able to link to code examples from the API docs.

Thoughts?

+1. A huge thumbs up for a place to hold examples.

Quote from: jrotering at Jan 25, 2011, 10:01 AM

One thing I think would greatly improve the overall documentation (and hence usability) of Revo would be to build up the quantity & quality of API usage examples - particularly examples where real-world problems are solved. I recently used modParser->collectElementTags() for the first time, and found it quite handy - particularly the &$matches array that it returns. Since I hadn’t seen this used anywhere before, I thought it would be a good idea to supplement the documentation with an example of how to use the &$matches array in a plugin (I used it in an OnBeforeDocFormSave plugin to add output filters to certain tags).

The problem is, I couldn’t figure out where to add this example. The RTFM docs don’t have anything on modParser - splittingred explained to me that a decision was made to keep the API stuff in api.modx.com (and not have to manage it in two places). But the API docs are auto-generated by phpDocumentor - so they aren’t the place to add code examples.

Here’s my proposal: examples.modx.com. Use the same skeletal structure as the API docs - class-by-class, method-by-method. Developers could submit examples, and users could rate the examples with a star or thumbs-up/down system. And/or comments. The auto-generated API docs could be easily modified to add an ’examples’ link that would take you to the corresponding user-submitted examples for that particular method, and you could browse for the highest-rated examples.

Or this could be handled entirely by the user community I suppose. But it would be really nice to be able to link to code examples from the API docs.

Thoughts?

I don’t think the MODX core team has the resources at this time to develop something like this, but honestly, the best solution is for examples to go in the API docs. However, since this isn’t really plausible at the moment, given that API docs aren’t real-time, nor are they easy to edit (you have to send a pull request from Git), we’ve added a Confluence space here:

http://rtfm.modx.com/display/examples/

Each example can be tagged ’revolution-20’ or ’revolution-21’, etc, to specify what version it accepts. This may not be optimal, tbh, and we’re open to suggestions. There’s a few problems with just doing a straight-up wiki:

• Each example needs to note what version of MODX it supports. Some examples may work with 2.0.x, but not 2.1.x.
• The examples need to be searchable and easily linkable.
• Examples need to be ’filterable’ by version - IOW, display only Examples for Revolution 2.0.x.

The Confluence space we made solves #1 and #2, however 3 is a bit lacking. That said, I’d post examples in that structure shown in that space, and ’tag’ them with ’revolution-20’, etc.

For now, I’d do that, until we can get some cycles to make a better solution. If you need access to it, post your username in this thread.

Shaun, do you think it’s ultimately better to have them in the PhpDoc headers, or should they be in a separate API section?

Quote from: BobRay at Jan 25, 2011, 11:39 AM

Shaun, do you think it’s ultimately better to have them in the PhpDoc headers, or should they be in a separate API section?

Well, there’s a few problems with putting them in the PHPDoc headers:

* They’d have to be written and put in there pre-release, since phpDocs are built for each release - likelihood of that happening: 0%
* They’d have to get in there via a GitHub pull request that only modifies that release, not develop, that is then approved, and phpDoc would have to be re-run on that current release branch.
* We’d have to expect contributors to said examples/docs to know how to use Git

All in all, some unrealistic expectations.

What would be better is to have links in the PHPDoc methods/headers that link to a place where Examples for said methods/classes could be submitted, reviewed, rated, etc.

I figured that once they were in the PhpDoc headers, they’d stay there (and I know someone who uses Git ), but I hadn’t considered the pain of updating and improving them.

Putting a link in based on the class or method name is a much better idea. Is there a way to auto-generate an empty page for each of them? Php.net must do something similar.

I’m sure there is, it’s just not as high a priority for the MODX Core Team right now.

We’ve discussed it as a future solution. For now, we’ll use the wiki, until we can get some time to provide such a solution.

there will be a lot of scenarios.
just consider to blog it.
google will take the rest.