API documentation suggestion

[Guest]

Welcome, Guest. Please login or register.
Did you miss your activation email?

1 Hour 1 Day 1 Week 1 Month Forever
Login with username, password and session length

[Mitch]

I have a suggestion for the API documentation. In most API calls I miss an explanation about what the return value of a function actually is. For example http://www.modxcms.com/dbapi-update.html From the information about the function I don't know what the value of $rows_affected is supposed to be after I call the API function. Does it return the number of rows that were updated? Does it return true if the update was succesfull and false if the update failed? The only way to figure it out is by reading the code

The nice thing about an API is that you don't have to know about how the function is implemented, only how you need to call it.

Also the code that is shown in the documentation does not match the code in MODx itself. I would suggest to remove the code from the documentation. It is just too hard to keep it in sync with each release and is not needed cause if someone wants to have a look at the code you can just look into the MODx code.

[OpenGeek]

Hello Mitch

Points well taken and agreed.  MODx 1.0 is in development and will feature a new object-oriented API complete with proper API documentation including descriptions of variables, parameters, and return values.  This will be generated automatically when we build a new release of MODx from 1.0 forward, so multiple versions of the documentation can be maintained in archives for back-reference, and the latest will always be available from the site.  And since the API documentation will be generated from the code comments, all the information will also be available to programmers who prefer to check out the code.

I'll try and get some of the current documentation updated for the 0.9.5 release in the interim, but can't make any promises.  If someone wants to volunteer for such a task, feel free to contact me via PM to discuss.