Suggestion for api.joomla.org
Jinx
You have done an excellent job with the new API interface. I would just
like to offer one suggestion. At the moment the API documentation
offers all the packages that are present in Joomla! 1.5. I would like
to suggest to only show the the real Joomla! Framework, being all the
packages in the libraries/joomla folder.
I see a couple of reasons to do this :
- it will make it easier for people to find the actual Joomla! API's
- it will re-inforce the importance of the new framework
- it will keep people from messing with any of the third party
libraries directly, most of the libraries included in 1.5 are either
wrapped by Joomla! specific API's or are only provided for BC reasons.
We could provide a list of the third party packages that are inlcluded
with references to their documentation. This will also allow us to
point out which of these third party packages are deprecated and only
included for BC reasons.
What do you think ?
Johan
Chris Davenport
Yeah, this was a decision I agonised over for some time and I can't
argue with any of the points you make. Apart from a natural tendency I
have towards achieving "completeness", what swung it for me was that
phpDoc throws lots of errors if I restrict it to just the Framework. The
errors are because of "missing classes" caused by those Framework
classes that wrap/extend 3P libraries.
The ability to explore the codebase for the whole of Joomla! is very
useful. Seeing how the Framework is used in a particular component, for
example, can be of great value to 3PD's. The case for keeping 3P
libraries is much weaker. Some are not well documented and we have no
control over their documentation quality.
Since you've brought the subject up I'll commit some of my thoughts that
have been in the back of my mind for some time now.
These are the "levels" at which we could operate the documentation:
0. (the null option). Include everything, like we do at the moment.
1. We could, as you suggest, restrict phpDoc to the Framework only.
Personally I think that is too restrictive.
2. We could restrict phpDoc to the Framework plus Joomla! CMS. In other
words, exclude all 3P libraries. The downside to this is that there is
much useful information in the 3P library docs that is not present in
the J! wrappers (nor ever likely to be). We would need to compensate by
adding and maintaining links to 3P library doc sites.
3. As (2) but exclude only the deprecated 3P libraries.
Here's my proposal:
1. Restrict api.j.org to Framework only (option 1).
2. Setup a new docs.j.org (or documentation.j.org?) with the full monty
except the deprecated libraries (option 3).
I think this would give us the best of both worlds. Most people will
use api.j.org and the links from the wiki and other documentation will
continue to point there. But for those who need more we have that too.
It also means that api.j.org really is just for the API!
I take your point about people messing with 3P libraries directly
instead of working through the J! wrappers, but rather than remove the
library docs altogether I think it would be better to have more
information on the dev wiki. Perhaps a page for each library detailing
how to use the J! classes. This would make it much less tempting to use
the libraries directly.
I'm open to argument of course. :)
Regards,
Chris.
In message <1167330443.1...@48g2000cwx.googlegroups.com>, Jinx
<jjan...@gmail.com> writes
--
Chris Davenport (chris.d...@joomla.org)
Joomla! Core Team Member (http://www.joomla.org)
Joomla! Documentation Workgroup Co-Leader
Joomla! Developer Documentation Team Leader
Jinx
I would suggest to choose option 3 and also exclude the Joomla! CMS.
My reasoning : it's not our goal to fully document the CMS classes
(components, modules, plugins). The extensions also don't contain any
public API's that developers can use in their own extensions. Including
them only creates confusion as to what is part of the actual framework
and what not.
Thoughts ?
Johan
Chris Davenport
I've been playing with this recently to see what it looks like. The
answer is it looks fine but for one tiny problem with JLoader.
JLoader has phpDoc tags that indicate it is part of the CMS (subpackage
Libraries). But it is a required part of the Framework.
Now I could simply change @package to Joomla.Framework and remove the
@subpackage tag. This will group it with JFactory, etc. in the phpDoc
output. But loader.php is not in the same directory as factory.php,
etc.
Personally I think it makes sense to move loader.php from /libraries
into /libraries/joomla/ (and change the tags). Naturally this implies
some code changes in JLoader itself and the CMS code, but I think that
logically we should have all the Framework code in a single
(sub)directory.
What do you think?
Regards,
Chris.
In message <1168173828.7...@11g2000cwr.googlegroups.com>, Jinx
<jjan...@gmail.com> writes
--
Chris Davenport
chris.d...@joomla.org
Ian MacLennan
I've just received instructions from Louis that no commits are to made
to the SVN until further notice. Louis will be in touch with Chris to
get everyone back up and running ASAP.
Ian