fixing the Joomla API documentation

[Marius van Rijnsoever]

Hi All,

Fantastic job again on the release of Joomla 1.6.0 stable. Amazing
amount of hard work done by so many people has really paid off!

Now that we have a stable version released I would like to bring an
important point forward. We have a beautiful new framework, with
inadequate and inaccurate documentation/api. The problem is that there
is no defined standard in Joomla for php docblocks (sections of
comments that document how functions work). In addition lots and lots
of docblocks are missing, incomplete, incorrect or wrongly formatted.
To see the scale of the issue for yourself here is a sample error
output from phpdocumenter (this link only lists missing or obviously
wrong docblocks and not any with incorrect/missing information,
therefore the scale of the problem is much much bigger)
http://doc.joomladev.eu/api6/errors.html

Now I am not the sort of person that just complains and complains
without offering to get his hands dirty to fix the issue. This issue
was raised 6 months ago and I created a test patch to fix the issue
(was accepted into svn) and offered to implement it for the whole of
the Joomla framework. There is no point in having a perfectly
documented framework if it does not work, therefore understandably
these issues were deemed not urgent and were not addressed. Now that
we have a stable release, expecting developers to upgrade extension
and are planning to release Joomla as a framework (not only for
CMS's), my opinion is that having framework documentation is very
urgent.

Here is what I am proposing:
1) Define and document the docblock standard that applies to the whole
core (consensus was already reached on most of this in previous
discussion on this list)
2) Create a new branch on the SVN where the documentation blocks can be fixed.
3) Fix one subdirectory of the library as a testcase and if successful
do the whole joomla code
4) merge the branch back into the joomla development trunk
6) Switch from wiki entry system (gets outdated very fast and is hard
to keep updated) and switch to doxygen for generating API's.
7) have a code sniffer profile for doc-blocks errors only to ensure
the joomla API is accurate and complete (this can be run from within
eclipse)

Just to give you a sneak peak at how nice doxygen is, here is a
comparison between our current api/wiki and doxygen generated api:

http://www.jfusion.org/api16/class_j_form_field_combo.html
vs
http://docs.joomla.org/API16:JFormFieldCombo

http://docs.joomla.org/API16:JPagination
vs
http://www.jfusion.org/api16/class_j_pagination.html

Any feedback on this? Thanks for your input, Marius

[Matt Thomas]

Hi Marius,

First of all, I want to thank you  for all your hard work regarding this. I fully agree that having useful documentation is key to engaging developers as well as providing a good example for those that come after us. I think this is a great thing to focus on now that we have 1.6.0 out and have established the foundation for future versions of Joomla.

+1 from me.

Thanks!

PS: I've included the JBS list on my response so that they take part in this conversation.

Best,

Matt Thomas
betweenbrain | Construct Template Framework | Sub-Templates Explained

--
You received this message because you are subscribed to the Google Groups "Joomla! General Development" group.
To post to this group, send an email to joomla-de...@googlegroups.com.
To unsubscribe from this group, send email to joomla-dev-gene...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/joomla-dev-general?hl=en-GB.

[elin]

From my understanding, the wiki is used for really specific reasons, namely that is it extremely modularized and can be transcluded http://en.wikipedia.org/wiki/Wikipedia:Transclusion which makes it ultra flexible for creating documents in different formats. It's not as though people are manually entering the data into the wiki but we certainly should make sure that it is being updated at each release. 

I think it's a great idea to open a branch and have a group of people working on the standardization of doc blocks. It's the best way for making these kinds of massive but small changes, if that makes sense. We did that with the php strict work before release and it really helped reduce crashes with each other and conflicts with the trunk (as long as you are good about updating your branch to trunk every time you start to work).

Also, it would be great for people to take on adding examples to the wiki. even though it was kind of unfair to pick JPagination as as an example, there is a code example  and it would be great to see more. 

It's really simpler to keep a discussion on one list and not have two separate threads that get all tangled up. Of course good API docs are important to the audiences for all 4 lists, but since it's Marius's thread and he chose general dev let's keep the main focus here. I think actually the gen dev group is probably a great one to take this on since 3pds use the API every day and probably have tons of great examples to share too.

Maybe someone from the PLT could get with Marius for setting up a branch and Marius can be the go-to person for people interested in helping with this project? 

Elin

[Janich]

I think its a great idea.

One of the main ressources when learning joomla for me, have been the
api.joomla.org.
Its such a valuable ressource for both newcomers and more experienced
developers and we should really try and keep it concurrent with any
latest release(s).

I have no insigt or experience in doxygen, but I do like the existing
phpdoc output.
Would it be a problem to have multiple versions of the same code in
there? (eg. doxygen, phpdoc, html, downloadable)

Anyway.. first things first.
We need a branch for this and some plan for it as well.
I can probably help on this, but dont have so much time on my hands
atm.
Make some simple organised projectpage and Im in. :)

On Jan 18, 4:48 pm, elin <elin.war...@gmail.com> wrote:
> From my understanding, the wiki is used for really specific reasons, namely

> that is it extremely modularized and can be transcludedhttp://en.wikipedia.org/wiki/Wikipedia:Transclusionwhich makes it ultra