The Joomla! Forum ™

Hi there,

I think Chris mentioned a while ago, that in the long run, he would like to see the Joomla documentation somehow will have the same functionality like the PHP documentation. I have a question about the ability to add comments and notes to Joomla documentation sites.

Leaving notes and code examples can be of great help for the users. Especially when it comes to the Framework documentation, code examples can be really helpful. I wonder how you agreed to handle these code examples and how they should be submitted.

Right now it seems like we do it the wikipedia way. Everyone can edit the page, and if someone wants to leave a code example, you just paste it into the "Examples" section. Unfortunately this takes away the possibility to force some styling and information rules on the comments. How would we visibly devide one comment from another. How do we make sure, that the person who leaves a comment, does so at the end/beginning of the comment lists and not in the middle. How do we make sure, that people somehow give their comment a title, or leave their name, so that other people can reference comments?

A second option would be to use the discussion page. This would also be very wiki-like. However I have the feeling, that this is the space where the content of the article should be discussed, and no code examples should be left. This is how it's used right now, and it makes sense.

PHP is using a commenting system. And I think this is a good way to go. Comments are automatically styled, and posted. This ensures some order within the code examples.

The ArticleComment Extension could help us with that.

I wonder what you think about these thoughts. Maybe you already have discussed this before. If so, just post me a link, so I can get an update.

Hi,

First of all, thanks for the great work you've been doing on the API Reference. It really is appreciated.

I'd like to encourage people to add comments to the API Ref pages in the manner of the PHP manual. It looks like we will have to make it more obvious that people are allowed to add comments. Just giving people blanket permission to edit anything in the wiki hasn't really worked.

The ArticleComment extension looks like it could be worth a try. I'll check it out on my local wiki first and see what it looks like. Thanks for the suggestion.

Regards,
Chris.

_________________
Joomla Leadership Team - Production Working Group

Joomla Web Services http://www.kickstarter.com/projects/964120480/joomla-web-services
Lion Coppice http://www.lioncoppice.org

Hey Chris,

thank you. I will continue working on the API reference whenever I have the time. The following lines are not questioning anything. They are just me thinking...

I haven't really understood the strategy of the api documentation yet. In my opinion putting a comment section for code examples to api.joomla.org would be great. I'm a developer, and the best about the phpDoc is that (if neccessary) you can dig into the code with one click. That's something crucial for understanding what's going on, and it can't be done with the wiki. Code examples in the comment seciton, that show you how to use objects, what they do, and how they intereract, is just what's really missing. I think the core developers would also be a lot happier if more extension developers would understand the power of the tools they have at hand.

At the same time I'm thinking that once we add a comment section to api.joomla.org, there is almost no reason left to keep the api reference on the wiki running. I saw the main benefit in the wiki, that we could add code examples.

A big advantage of the wiki API reference is, that you can also link tutorials, add paragraphs that explain the pattern that is implemented, and how the objects are inteneded to be used. Of course you could do that in the comment section of the api.joomla.org, but that's no good way to do it.

I don't want to seem extreem, but wouldn't it make sense to try to find a way to add this functionality to the phpDoc reference, instead of creating two parrallel references that overlap 80%.

The @tutorial and @example tags of phpDoc could be used. Ok, this would reduce the chance that everyone can contribute to the api reference, but very few are using this chance anyway. Besides, they would have the chance to contribute by code examples in the comment section.


Sooo, my point is: Keeping the limited resources the documentation team has in mind, wouldn't it be smart to:

1. Add a comment section to the phpDoc reference
2. Create tutorials and code examples for the classes and methods that need them, and include them with phpDoc tags.

I think this could actually be less work than creating the full api reference on the wiki, and keeping it up to date with every new release. It would still be a lot of work, but in the long run, it would make it more maintainable.

I'm wondering what you're thinking about these ideas...

Hi,

Sorry for the delay in responding. It's been a struggle keeping up with client work just recently.

This is something that, quite rightly, gets revisited from time to time. Partly because of its obvious importance, but also because the current solution is less than ideal.

We've been saying for many years (since Mambo days) that example code is one of our most important resources, yet getting people to contribute such code is still a long way short of where I'd like it to be. Moving to the wiki has certainly improved things greatly, but there's still room for improvement.

I agree that it would be nice to have a single resource for all API reference information rather than having it split across api.joomla.org and the wiki. Unfortunately, api.joomla.org has some quite significant problems that, while probably not insurmountable, make it a less certain prospect for the future.

The biggest problem is the phpDocumentor code itself. It's archaic, spaghetti code that is hard to maintain and really, really hard to extend. Ideally, the entire package should be rewritten from scratch using modern OOP techniques, but development seems to have slowed to a crawl and I think this is now unlikely to happen.

We also have a looming problem in that the phpDocumentor code that we're currently using, which admittedly is not the latest version available, is not compatible with Joomla 1.6, by which I mean that some aspects of the 1.6 codebase make phpDocumentor fail completely, with no output. Unless that can be fixed, api.joomla.org will be a 1.5-only resource and we'll be forced to move to something else for 1.6 onwards.

You're right about the possibility of using the @tutorial and @example tags and this is something we experimented with some years ago. It works, but is cumbersome and consumes a lot of server resources. Eclipse seems to ignore them so they would only really be useful on api.joomla.org itself.

Without significant developer input I don't think that phpDocumentor is going to be something we will continue to use in the future. Note that this is quite different from saying that we should abandon using the phpDoc tags in the code itself. These are now something of an industry standard and are used by many other packages, perhaps most notably by Eclipse, but also by other standalone documentation packages such as Doyxgen.

A different approach, which I'd be keen to explore further, is to abandon api.joomla.org and move the data into the wiki. MediaWiki has the considerable advantage that the code is well-maintained and it has a comprehensive API which can be used to automate the import and export of data. What I'm thinking is maybe using Doyxgen or a similar package, to generate the raw data, then write some code to batch import it, on a regular basis, into the wiki.

It would then be a matter of "transcluding" pages or page elements into the main reference pages, which could themselves be augmented by user-contributed material, possibly using the ArticleComments extension, or something similar. For example, a typical class page might contain "tags" which effectively pull in the short and long descriptions from the phpDoc tags, maybe the prototype and the method list too. Interspersed with this automatically generated content, you could then add user-generated content in regular wiki syntax.

At the end of the day, what we do is still largely constrained by the tools we have available, and they leave quite a lot to be desired. But even given the tools we have, I think we can find an approach that will work better than the way we do things at present. So please, continue to think about and explore these ideas. I'm sure that we can make a difference and improve the documentation for the future.

Chris.

_________________
Joomla Leadership Team - Production Working Group

Joomla Web Services http://www.kickstarter.com/projects/964120480/joomla-web-services
Lion Coppice http://www.lioncoppice.org

Interesting thoughts. So what you want to do is:

1. Use a documenation package like doxigen to gather the documentation data (let's say in XML format)
2. Write some PHP or Perl code to:
2.1 Parse the XML data
2.2 Generate Class and Method Information in Wiki-format
2.3 Use the Media-Wiki API to automatically update/create new wiki-pages where these information are stored

3. Then these class/method information pages are included into the reference pages using wiki-tags.

Wiki-Users would then be able to add code examples and link tutorials to the reference, but the actual Framework reference is created and updated automatically.

This would be quite some project. I took a look at Doxigen, ran it with the Joomla 1.5 source-code and took a look at the XML output: It seems like Doxigen is getting along with phpDoc style comments quite well. I say quite, because I immeadiately recognized one minor and one major flaw, which might make a complete rework of the code-documentation necessary.

The minor flaw is, that (like phpDoc) Doxigen differentiates between brief description and detailed description. However, Doxigen does interpret phpDoc brief descriptions as detailed descriptions.

A major flaw is that Doxigen expects the property name of a method where phpDoc expects the data type. This means that the "string $query" property would be named "string" by Doxigen.

Leaving these two observations behind for the moment, I'm pretty sure that this could be an interesting project, and if planed well, could also be easily extended. I'm talking about extensions, because in the end, I would really like to be able to access the source code from the API reference with just one click, like it is currently possible at api.joomla.org. With all the information at hand, that doxigen provides us, it would be easy to write a class that pulls the source code out of the file, and creates a new/edits an existing wiki page and puts the source coude into

tags.

Well there certainly needs to go a lot of thinking into this. But this is a surely refreshing idea, and worth looking into.

What an interesting discussion

We have a "sister-project" on http://wiki.joomla-nafu.de which is doing a german "fork" of the framework dokumentation.
As i am more a coder than a secretary i had to write some scriptings to automate some task.
* A script that acts like a "mini phpdocumentor" with wiki syntax output - it parses Joomla! classes and methods and outputs them in wiki syntax - see: http://jdoc.nik-it.de/
* A second script is used to display the actual source code of every method on the wiki page - i agree, that the source code itself is the best documentation at all. This works with a previous generated file holding class/function names and line numbers. You can see an example here: http://wiki.joomla-nafu.de/joomla-dokum ... File/write (Quellcode = Source code ) - with a new version you have to update just one file, and upload the J! sources - the wiki pages remain the same. This is done with a custom mediawiki extension.

What do you think ?
Nikolai

_________________
Nikolai - http://www.nik-it.de

Hi Nikolai,

I'm impressed.

I'd like to see this developed further, with a view to incorporating it into the English wiki. I downloaded your code but couldn't see any mention of a license. Would you consider releasing it as GPL? And maybe start a JoomlaCode project so a small group of us could see where we can develop it?

Incidentally, you might like to add a little "wiki magic" like this:
Add this to your interwiki table:
Prefix: en
URL: http://docs.joomla.org/$1
Then in each class page add this: [[en:<class-name>]] and in each method page add this: [[en:<class-name</<method-nam>]] where <class-name> and <method-name> are the Joomla class and method names respectively.
Now notice that MediaWiki will automatically add a link to the equivalent English wiki page in the left column, under "In other languages" (well, actually the German equivalent of that). You can do that for any page on your wiki that has an equivalent page in the English wiki. And, of course, this can be extended to other languages too.

Great work.

Chris.

_________________
Joomla Leadership Team - Production Working Group

Joomla Web Services http://www.kickstarter.com/projects/964120480/joomla-web-services
Lion Coppice http://www.lioncoppice.org

I really like this work too. This already solves many of the discussed problems. With some work this extension might automate even more of the documenation work.

I really would like to see this in JoomlaCode too. I have some ideas, how this extension could become even better.

Impressive response - glad you like my work.

As for the license: Of course it's GPL ! I just forgot to mention - busy coding..

The code is held on Google code, as it is (was) more MediaWiki related. You can find it here: http://code.google.com/p/jmediawiki-extensions/
If you would like to move it to joomlacode - fine by me. Otherwise anybody interested could have write access to the google code project.

As for the wiki-magic: Shure it would be nice to have a mutilingual framework documentation.

_________________
Nikolai - http://www.nik-it.de

Hello,
please don't forget this

The first step for automatic code documentation is obviously - the code must be "valid".

Wilco Jansen wrote an interesting Article on JFooBar Blog about how to "validate" coding standards.

I wrote a small script that checks the @param elements of the method DocBlocs - see the output for svn #12683

Putting all of this pieces together we should be able to produce some beautiful source code and - a good lookin' Documentation

_________________
Nikolai - http://www.nik-it.de

I played with Doxigen this week, and the xml output is very detailed.

I'm wondering if it wouldn't be easier to use this as a source for the documentation. I see the following advantages:
- The parsing of the code is outsourced to a very good, well maintained DocParser
- The Doxigen xml output contains many information, like properties, method parameters with initial values
- Doxigen supports many different programming and scripting languages. The final result could be interesting for more people than the Joomla Doc Team.

Let's discuss this.