API Documentation [was: Core functions jungle]

I all... I know that core coders are a lot busy, so it is difficult to think about a full MODx API documentation in short times...

anyway, I would ask if it is possible to have only a LIST of currently supported functions, so that coders like me are sure not to use deprecated or unuseful functions...

just something like

$modx->dbQuery()
$modx->event->alert()

and so on

thanks for all...

Is this what you are looking for? http://modxcms.com/api-quick-reference.html

The DBAPI is also documented at http://modxcms.com/dbapi.html

I think that these are not up to date, Jason.

They’ve never been completely finished in the documentation, btw. We need to work on that.

How do we know, which API inside MODx that we can use? Where is the best place to look for it, and what’s the sign so that we can identify, which function that we can use and which one that we can’t.

Usually I just skim through the document.parser.class.inc.php, and pick which function that I would like to use. Is all the APIs are the one after line 1151?

Maybe this will help us a little bit.

One more thing though, it’s better for memebr like me, madmage, or zenmaster that know about PHP more than some other members in here to help writing a description for each API, and let the core coder/core team to just approve it. What do you think about this idea?

We all can work together to improve this community, don’t you guys agree with me?

Yes Wendy, I agree 100%. We need people with knowledge of PHP who can describe these in better terms than the geeks that write the stuff to contribute here. And also, the public API functions are indeed the ones which are between this comment:



and this one:



in document.parser.class.inc.php

Cool,

As I expected, but I always cross the boundaries, everytime I build something. lol

So anybody dare to take on this challenge?
We’ll use this topic to post whatever description to specific API taht you guys want to contribute, then the Documentation team will do their part to make it pretty and make it available on the documentation site.

Remember, at least somebody need to start writing this documentation, the more people willing to do the writing, the better the documentation that we have. If we have a complete documentation of MODx, it will eventually benefit you guys more, rather than the core coder. Nothing to worry if you guys describe it wrong, because we have our PHP MASTER or this great COMMUNITY to fix the description.

Allrighty, the race BEGIN!!!

Quote from: OpenGeek at Jan 11, 2006, 11:14 PM

I agree 100%.

And me!!

I would love to help out (and maybe learn something at the same time).

What will be the impact of the "Tattoo" rework though? Will it have the same API or will it all need doing again?

I would like to see a full QA system in place, with standards, specifications, and peer reviews (forgive me if there is already such a thing).

We could take this project from "shining" all the way to "gleaming" ".

IN regards to Tatoo, I think the core team member will have a better view compare to me. But as far as the conversation from the forum, I’m assuming that the system will be re-work from the a scratch, which means that the use of API and the API itself will be different. I believe it will based more on class and object, instead of half class support like what we have right now.

But... MODx will still be supported I believe, because the current version is quite mature, and we can see that the progress will keep on going until it reach to the point where the limitation is based on the MODx current architecture. I’m not saying the current architecture is bad, but I’m saying that when building MODx, I believe they try to make it compatible with PHP 4 or under, plus MySql 4 or under. From my knowledge, the evolution from PHP 4 to 5 and MySql 4 to 5 is really2 huge. There are a lot of better stuff that we can do with both of them, such as 80% OOP support in PHP, and I believe a standard and advanced stored procedure support in MySql 5 as well.

For now, I can see MODx as the pioneer product to support a much older version of server, and it’s a lot ligher and easier to understand, in terms about the current architecture.

We can see it as Windows 2000 with Windows 2003. We still see a lot of people using Windows 2000.

So don’t affraid to write the API description for the current MODx, because we still have a long way to go with MODx.

Sincerely,

Thanks Wendy, couldn’t have said it better myself.

The new API is coming along, is much more modular (based on and structured as packages), and over the next few weeks, Victor and I will be working on a standard development environment that will feature auto generation of API documentation, most likely using PHPdocumentor, as well as automated unit testing using phpunit; automation provided by Phing. BTW, if you don’t use Eclipse and PHPeclipse for your development, it really is worth the learning curve, especially if you are interested in the Tattoo path of development; just a quick plug for what I consider an indispensable tool in my arsenal.

But anyway, I will see what I can do personally about going through the current docs and updating/providing examples where I can; though I’ve been extremely busy the first weeks of this year, and it may be a few days before I can revisit them properly. In the meantime, if anyone has better descriptions or code samples, please feel free to contribute them.