API documentation ideas

[Chris Davenport]

I want to gather some ideas about what we want to see from the developer documentation and more specifically the API documentation, in the next year or so.  We've had several attempts at providing some sort of API documentation over the past years, with mixed results.  I think the time has come to take a look at what our ideal API documentation would look like and see if there is some way to make significant improvements.

To set the scene: at present we have api.joomla.org which is generated automatically by phpDocumentor.  However, that package has some shortcomings which makes me wonder if it's the right tool going forward. We also have a collection of pages on docs.joomla.org that were automatically generated using Doxygen, then processed with some custom code and pushed into MediaWiki using the web API.  This worked and it allowed the possibility of adding user contributed comments that would persist even when the underlying pages were updated.  However, various things changed including updates to the MediaWiki software which caused it to stop working and I haven't really ever had time to go back and fix it.

So, to share my thinking on the subject, I'm very tempted to write our own documentation generator package as a standalone Joomla application, along these lines:

* Provide a web interface similar to php.net (but better looking ;-)), which would allow moderated user contributions to be added to class pages (at least).

* Provide a web API that would allow integration with tools such as Eclipse as well as mobile clients.

* Provide export options so we could push data through publishing toolchains that would give us downloadable documentation in PDF and various other formats.

* Facility to link to or embed other documentation sources such as MediaWiki pages or Github wiki pages and gists, YouTube videos, and so on.

* User contributions that would persist across minor versions, but would not persist across major versions.

* Well-known URLs that would remain valid over time.  For example, classes will *always* be available using URLs of the form api.joomla.org/{classname}, method documentation will *always* be available at api.joomla.org/{class}/{method}, and so on.

* Version disambiguation so that api.joomla.org/{classname} will be a list of versions where the class is available (with links), with specific class pages at api.joomla.org/{classname}/{version}.

* Automatically executed from Jenkins for the very latest versions.

* Modern user-interface (something for the UI designers to ponder on).

* Filtering and searching.

* Integration with GitHub (eg. links to pull requests, etc).

* Multi-language user interface.

I'd also like to look at using the same tool to document the CMS classes.  We could do things like cross-referencing language strings, help screen key references, and so on.  Since this would be a Joomla-specific tool running on top of Joomla, we could do pretty much anything we want.

So what's your vision of the ultimate Joomla API documentation?

Chris.

--

Chris Davenport
Joomla Production Leadership Team

[Don]

apigen.com

I use it locally for browsing platform API as of last week, and I like it a lot. 

Sent from my iPhone

--
You received this message because you are subscribed to the Google Groups "Joomla! Platform Development" group.
To unsubscribe from this group and stop receiving emails from it, send an email to joomla-dev-plat...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
 
 

[Don]

Sorry - I should have read the whole thing before I replied.

I like the concept, of a API generator, and the ability to control the code would be a big bonus (as we can account for changes to our underlying framework). It would be like API-ception. A change in the underlying Joomla Platform API would mandate a change in the API doc builder, which would document the change. 

Mind === blown

Sent from my iPhone

On Feb 24, 2013, at 1:48 PM, Chris Davenport <chris.d...@joomla.org> wrote:

--

[Michael Babker]

I quickly installed apigen and generated the docs for the joomla-framework repo, must say I'm impressed.  Really like how it shows the class inheritance, works with the namespacing, and has all the pertinent info from the classes.

Add in some of the user contribution points that Chris mentioned, and I think we've got a winner on our hands.

[Donald Gilbert]

From within a joomla-platform/apigen folder, run:

apigen -d . -s ../libraries/joomla/ --title "Joomla Platform API Reference" --deprecated yes --template-config "/Users/admin/pear/data/ApiGen/templates/bootstrap/config.neon"

Just change that last part to your ApiGen install directory templates/boostrap/config.neon

It gives you a nice bootstrapped template. the Phoca folks did it here: http://www.phoca.cz/joomla/api/package-Joomla.Platform.html

[Rouven Weßling]

Quick FYI phpDocumentor 2 (which isn't quite stable yet) will be the common successor to both phpDocumentor and ApiGen.

Rouven

[Andrew Eddie]

Personally, I don't ever use the generated API docs. I rely exclusively on Eclipse to provide code assist etc. 

My gut feeling is do the minimum required in terms of getting some sort of published docs out there. I certainly like the idea of being able to comment on the API docs, but in all honestly I'm not convinced more than a handful of people would use the feature.

My personal preference would be putting effort into making sure the DocBlocks are really, really good, as well as any README or manual files.

My 2c.

Regards,
Andrew Eddie
http://learn.theartofjoomla.com - free tutorials and videos on Joomla development

[Donald Gilbert]

OK - let's use phpDocumentor 2 then - it makes the most sense.

[Donald Gilbert]

FWIW, I prefer the bootstrap template of apigen to anything phpDocumenter offers

[David Hurley]

+1 - I was just typing the same thing. The UI of ApiGen is is much friendlier and "prettier" than PHPDocumentor.

-

Thanks,
David Hurley
Joomla! Community Development Manager

[Chris Davenport]

The problem with all of these documentation generators (Apigen, Doxygen, phpDocumentor and others) is that they produce what is basically just static HTML (plus some JavaScript).  That's fine as far as it goes, but I think we can do much more by building an "active" documentation platform.  In particular,

* We can provide a much, much better search capability.  No more relying on Google to be able to find stuff in the API docs.

* We can support user contributed examples, comments, etc., much more easily.

* We can provide an API that would allow external applications to consume our documentation as a set of web services.  Perhaps the front-end can be built on those same services.

Let's think beyond the rather limited set of tools that are currently available.  Let's start by dreaming of what we might achieve, then later we can pare it back to what we can actually deliver.

Chris.

[David Hurley]

One of the biggest benefits I see to the method used by PHP.net is all the user submitted comments and examples underneath each function. That has proven invaluable in some instances to properly understand the method, function or return values. I would highly recommend that we implement something that allows that level of interaction. 

I agree with your points made. The search functionality has to be fully integrated and not reliant on a 3rd party. 

Also, the ability to use the documentation through a web service is definitely key. This will definitely increase implementation opportunities.

-

Thanks,
David Hurley
Joomla! Community Development Manager

[Bakual]

I use docs.joomla.org (and to a lesser degree api.joomla.org) all the time since I never figured out how to install and work with Eclipse. Also it's good to have a link which can be shared if other developers have questions. I'd also like to see user contributed comments, which I think could be very valuable. There are classes out there where it's not that obvious how they have to be used.

[Donald Gilbert]

The docs wiki is, IMO, not what we should use for platform documentation. It's full of a mix of CMS and Platform documentation which tries to act like an API reference, but doesn't doa very good job. 

It was good for it's time, but again, not what I would use going forward.

[Michael Babker]

Personally, I find the information generated by those tools is exactly what we need as a framework.  So, the base of our app should duplicate that information IMO.  It's how we expand on that which we need to discuss, and I agree fully that a system like PHP.net would really be nice.

From: Chris Davenport <chris.d...@joomla.org>
Reply-To: <joomla-de...@googlegroups.com>
Date: Sunday, February 24, 2013 4:26 PM
To: <joomla-de...@googlegroups.com>
Subject: Re: [jplatform] API documentation ideas

[Andrew Eddie]

If you want to tack onto the project the idea that I can use the same tool to generate the REST API for my custom app., now I'm starting to get interested :)

[Andrew Eddie]

On 25 February 2013 06:44, Rouven Weßling <m...@rouvenwessling.de> wrote:

Quick FYI phpDocumentor 2 (which isn't quite stable yet) will be the common successor to both phpDocumentor and ApiGen.

Are you sure you aren't confusing ApiGen with DocBlox? 

I prefer the output ApiGen http://api.nellafw.org or even Sami http://api.symfony.com/2.2/index.html over phpDoc2.

This, however, is really nice as a total package in terms of output:

http://docs.sencha.com/touch/2-1/

Regards,

Andrew Eddie

[Chris Davenport]

Don't see why not.  I presume you're thinking along the lines of adding something to the docblocks, similar to this: https://github.com/LouisLandry/tester/blob/master/src/classes/service/hook/create.php

How about also including a live demo of the REST API, similar to this one: haltalk.herokuapp.com/explorer/hal_browser.html

Chris.

--

You received this message because you are subscribed to the Google Groups "Joomla! Platform Development" group.
To unsubscribe from this group and stop receiving emails from it, send an email to joomla-dev-plat...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
 
 

[Chris Davenport]

The Sencha docs do look nice.  Now, drop those ugly scrollbars, add in a generous helping of filters on the left-hand side so you can drill down by namespace, interface, package, sub-package as well as filesystem path and anything else you can think of, plus a search box with auto-completion, with everything Ajax-driven.  That's the sort of thing I had in mind.

Chris.

--

You received this message because you are subscribed to the Google Groups "Joomla! Platform Development" group.
To unsubscribe from this group and stop receiving emails from it, send an email to joomla-dev-plat...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
 
 

[Rouven Weßling]

On 25.02.2013, at 01:17, Andrew Eddie <mamb...@gmail.com> wrote:

On 25 February 2013 06:44, Rouven Weßling <m...@rouvenwessling.de> wrote:

Quick FYI phpDocumentor 2 (which isn't quite stable yet) will be the common successor to both phpDocumentor and ApiGen.

Are you sure you aren't confusing ApiGen with DocBlox? 

Indeed I am. I kinda purged DocBlox from my memory. Sorry about that.

Anyway, the most important point is that most of these tools are very template-able. So not only can we manipulate the output to our liking, we should also be able to use this to allow for comments.

Best regards

Rouven

[Amy Stephen]

In case you want to parse the Doc Blocks and simply extract data for the API, Mike van Riel, phpDocumentor 2 guy, pointed out https://github.com/phpDocumentor/ReflectionDocBlock

 

[Herman Peeren]

I'll ask Mike to JAB13 for a presentation; lives 45 km from the venue. Hope he can come.

[Herman Peeren]

Wow. Awesome! That can become something... beyond Joomla and phpDocumenter.

On Monday, 25 February 2013 20:10:56 UTC+1, Mike van Riel wrote:

Dear all,

Thanks to Herman's mail I just found out about this thread and I would like to at least contribute my thoughts to this process and maybe more.

First a short introduction for those who do not know me; My name is Mike van Riel and I am one of the two Lead Developers for phpDocumentor (Chuck Burgess being the other). My, and our, goal is to provide a super experience when it comes to the Documentation of PHP Projects, with a focus on API Documentation. 

Right, enough marketing speak.

I recognize a lot of great ideas in this thread that are at current unavailable in phpDocumentor (or any other Documentation Generator that I know of) and I could only wish that I had them all. I will also be the first to admit that phpDocumentor's template could use some improvements (painful admission, sorry) and I will be the first to want to improve that.

Is it possible for us to work together to make a set of kick-ass API Documentation for Joomla and in the process improve phpDocumentor for everyone?

None of the features mentioned above are impossible; phpDocumentor 2 was designed to be extendable (even more so with Twig support in the next release) so to be able to support this.

I have a lot to share, to tell and to listen to, and wish for us to work together. I think it will save the Joomla Project a lot of time, and benefit phpDocumentor as well.

What do you think?

Kind regards,

Mike van Riel

[Don]

That would be awesome Mike and what I secretly hoped would happen. 

Sent from my iPhone

On Feb 25, 2013, at 1:10 PM, Mike van Riel <mike.v...@naenius.com> wrote:

Dear all,

Thanks to Herman's mail I just found out about this thread and I would like to at least contribute my thoughts to this process and maybe more.

First a short introduction for those who do not know me; My name is Mike van Riel and I am one of the two Lead Developers for phpDocumentor (Chuck Burgess being the other). My, and our, goal is to provide a super experience when it comes to the Documentation of PHP Projects, with a focus on API Documentation. 

Right, enough marketing speak.

I recognize a lot of great ideas in this thread that are at current unavailable in phpDocumentor (or any other Documentation Generator that I know of) and I could only wish that I had them all. I will also be the first to admit that phpDocumentor's template could use some improvements (painful admission, sorry) and I will be the first to want to improve that.

Is it possible for us to work together to make a set of kick-ass API Documentation for Joomla and in the process improve phpDocumentor for everyone?

None of the features mentioned above are impossible; phpDocumentor 2 was designed to be extendable (even more so with Twig support in the next release) so to be able to support this.

I have a lot to share, to tell and to listen to, and wish for us to work together. I think it will save the Joomla Project a lot of time, and benefit phpDocumentor as well.

What do you think?

Kind regards,

Mike van Riel

On Monday, February 25, 2013 2:59:25 PM UTC+1, Herman Peeren wrote:

[Paul Orwig]

Hi Mike,

Welcome to the Joomla community, if this is your first time. You are very welcome here!

Thanks very much for your invitation to work together. I hope something will happen that will make both of our project's better and stronger.

Thanks Herman for inviting Mike to join this thread!

Best regards,

paul

[Andrew Eddie]

On 26 February 2013 05:10, Mike van Riel <mike.v...@naenius.com> wrote:

I have a lot to share, to tell and to listen to, and wish for us to work together. I think it will save the Joomla Project a lot of time, and benefit phpDocumentor as well.

What do you think?

Sounds cool. I had the pleasure of working with Josh and Greg in the past, many moons ago. It'll be like old times :)

Regards,

Andrew Eddie 

[Chris Davenport]

I think there is huge potential for collaboration and I look forward to sharing ideas.  I'm going to spend some more time looking again at phpDocumentor and see where it might lead us.

Chris.

--
You received this message because you are subscribed to the Google Groups "Joomla! Platform Development" group.
To unsubscribe from this group and stop receiving emails from it, send an email to joomla-dev-plat...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
 
 

--

[Herman Peeren]

Hi Mike,

There is no timetable, no clear goal and no committed working group (yet). Chris has done a lot to improve the wiki-documentation on docs.joomla.org over the years. One of the often heared wishes is to get better documentation, especially for the Platform / Framework, as it is essential for the productivity of (new) developers. Chris has now made some suggestions and some people have shared their opinion about it. It is still in an exploratory phase: looking what we have, what possibilities and needs are and choosing goals and tools.

I think, a next step should be  to set some clear goals that can be accomplished within an overseeable timeframe and get some people together who want (and are able) to commit to such goals.

The Joomla project consists of several parts, like the Platform (framework) and the CMS. We also have several channels of communication, like fora (mainly for users / integrators), etc. On Google Groups we have 3 main lists, which are mainly for developers: this Platform list, a CMS list and a general list. At the moment there are several discussions on the general list mentioning vision, leadership, setting goals, roadmaps, working groups and organisation. So questions about it are vivid, but there is no consensus on all points. That is also one of the unique aspects of the Joomla projects: it is more organic and less centrally directed than many other open source projects. Sometimes it is tiring, sometimes there is more debate than code and it always takes some time. But this typical process is also what makes it so unique. Most of the time things happen, because some people do it (because they just need it) and then they present it to the community.

I want to do some small tasks in this group and help getting it on the rails, but as I've set other goals for the near future allready (besides work, which is mainly custom Joomla components, mainly: to at last make Doctrine easily available in Joomla,  refactor some core classes with that and show the benefits of it for development), I cannot commit to a big task here. There is however one thing I'm especially interested in: to use our current Joomla (Platform and CMS) to develop some of the features we are talking about here. You talk about Twig, but we have our own templating system and some great frontend developers. Or should we integrate some Twig and what you did with it into Joomla (some people have a Symfony-allergy however ;-) ). Maybe we can even do something with Doctrine + Joomla in this project; then I'll certainly participate more actively.

What looks most promising to me at the moment are the points where we can "embed" phpDocumentor in some Joomla-application (be it a cms-component or platform-application) to add some extra features like user comments to documentation that is generated via DocBlocks. But that is just my idea, right now.

- Herman

On Tuesday, 26 February 2013 18:04:26 UTC+1, Mike van Riel wrote:

Allow me to elaborate a little on the current status of the project:

phpDocumentor2 is a complete rebuild of phpDocumentor1 and as such has certain features the original had not and is missing some features that the original did have. This is the main reason it is still in an alpha state, the code is mature but so far we have reserved the right to make BC breaks (mainly within the code itself; the command line interface hasn't had a BC breaking change for many releases).

At current I am in the middle of 'the last great push', which is a refactoring intended to solve blocking issues and improve performance with a significant amount. One of the issues blocked in the current version is the use of Twig. I am pushing this refactoring to be finished before end march and with that move phpDocumentor2 to the beta phase. The intention is to go live before the end of April or May (depending on the amount of bug reports).

phpDocumentor 2 is built with extensibility in mind and has the potential to provide all kinds of services (one of my experimental branches features a complete search solution using ElasticSearch). Even dynamic features such as comments are possible because when you use Twig you could choose to generate files with a .php extension, containing PHP code.

As I said, phpDocumentor does not contain all features that are mentioned in the opening post and the theme could use some love (or a reboot ;)). This is one of the things I need your help, great ideas and perhaps a little front-end (I can do it mediocrely; you probably have a clear view of what you want and how).

Which features would you like to see most of all, and in which way do you see the cooperation? Do you have a timetable? 

Kind regards,

Mike

[Chris Davenport]

Hi Mike,

My current thinking, obviously subject to change in the light of our conversations here, is that we would use a code analysis tool like phpDocumentor to generate a representation of the code that can be stored in a database (maybe from the XML that phpDocumentor generates?).  This data can then be augmented from other data sources such as Github, JoomlaCode, unit test results, other code analysis tools, etc.

We can then build a variety of applications to query and extract data from that database.  Obviously, the traditional documentation website (like api.joomla.org) can be created with PHP-generated pages instead of the current static HTML ones and we would have the full power of Joomla's templating system available to make that look really cool.  Although that could be built as a traditional Joomla component, it would be interesting to consider first building a set of RESTful web services, then building an application or component that would use those services to build the web pages.  I'm thinking that parts of the pages could be pulled in with Ajax calls rather than having entire pages being rendered server-side, but that's something we can experiment with.

Commenting would be quite straightforward since Joomla could easily support that.  Integration with IDEs and other external tools would also be straightforward given that the data would be accessible using a REST interface.

I'm sure ElasticSearch or some other standalone search engine would be great, but I'd prefer not to have to depend on external tools to support the search if possible because I have it in mind that whatever we develop will be made available to third-party extension developers to document their code and some of them might not be in a position to install such software on their servers.  Consequently I was thinking of using Joomla's own Smart Search for that purpose.  No reason why Smart Search should not be given a REST interface too.

Thinking about it, if the data can be accessed via RESTful web services, then it would make sense to look at having phpDocumentor's output pushed into the database using REST too.  It might be interesting to look at eliminating the XML parsing step and have phpDocumentor push the data directly using web services.

All the best,
Chris.

--

You received this message because you are subscribed to the Google Groups "Joomla! Platform Development" group.
To unsubscribe from this group and stop receiving emails from it, send an email to joomla-dev-plat...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
 
 

[Andrew Eddie]

On 27 February 2013 10:06, Chris Davenport <chris.d...@joomla.org> wrote:

I'm sure ElasticSearch or some other standalone search engine would be great, but I'd prefer not to have to depend on external tools to support the search if possible because I have it in mind that whatever we develop will be made available to third-party extension developers to document their code and some of them might not be in a position to install such software on their servers.  Consequently I was thinking of using Joomla's own Smart Search for that purpose.  No reason why Smart Search should not be given a REST interface too.

We are actually in the process of replacing Smart Search with Solr at work. It's been an extremely fruitful project, web service based and I could certainly seek permission to share the code.

Regards

Andrew Eddie

[Mike van Riel]

Hi Chris,

It is trivial to write a 'Writer' that writes the contents of the
Abstract Syntax Tree to a database or REST interface, so that is
definitely an option.

I recommend using a Writer instead of replacing the serialization
process as it will help gain performance and benefit from
'behaviours'; that augment the object graph 'just in time'.

I am afraid I have to disappoint you with regards to the XML; it is
deprecated and will be replaced with a serialized object graph with
the next release.
For compatibility reasons I am writing a compatibility layer but that
will be removed with version 2.1.

I'd like to point out, to provide a few options and insights, that
phpDocumentor2 is also capable of augmenting the Object Graph using
Behaviours (which are executed right before the transformation to
HTML).

I am looking forward to your, and the other collaborator's input.

Mike

On 27.02.2013 01:06, Chris Davenport wrote:
> Hi Mike,
>
> My current thinking, obviously subject to change in the light of our
> conversations here, is that we would use a code analysis tool like
> phpDocumentor to generate a representation of the code that can be
> stored in a database (maybe from the XML that phpDocumentor
> generates?).  This data can then be augmented from other data sources
> such as Github, JoomlaCode, unit test results, other code analysis
> tools, etc.
>
> We can then build a variety of applications to query and extract data
> from that database.  Obviously, the traditional documentation website

> (like api.joomla.org [4]) can be created with PHP-generated pages

> instead of the current static HTML ones and we would have the full

> power of Joomlas templating system available to make that look really

> cool.  Although that could be built as a traditional Joomla
> component, it would be interesting to consider first building a set
> of
> RESTful web services, then building an application or component that

> would use those services to build the web pages.  Im thinking that

> parts of the pages could be pulled in with Ajax calls rather than

> having entire pages being rendered server-side, but thats something

> we
> can experiment with.
>
> Commenting would be quite straightforward since Joomla could easily
> support that.  Integration with IDEs and other external tools would
> also be straightforward given that the data would be accessible using
> a REST interface.
>

> Im sure ElasticSearch or some other standalone search engine would be
> great, but Id prefer not to have to depend on external tools to

> support the search if possible because I have it in mind that
> whatever
> we develop will be made available to third-party extension developers
> to document their code and some of them might not be in a position to
> install such software on their servers.  Consequently I was thinking

> of using Joomlas own Smart Search for that purpose.  No reason why

> Smart Search should not be given a REST interface too.
>
> Thinking about it, if the data can be accessed via RESTful web

> services, then it would make sense to look at having phpDocumentors

> output pushed into the database using REST too.  It might be
> interesting to look at eliminating the XML parsing step and have
> phpDocumentor push the data directly using web services.
>
> All the best,
> Chris.
>
> On 26 February 2013 20:15, Herman Peeren <herman...@gmail.com

> [5]>

> wrote:
>
>> Hi Mike,
>>
>> There is no timetable, no clear goal and no committed working group
>> (yet). Chris has done a lot to improve the wiki-documentation on

>> docs.joomla.org [1] over the years. One of the often heared wishes

>> is to get better documentation, especially for the Platform /
>> Framework, as it is essential for the productivity of (new)
>> developers. Chris has now made some suggestions and some people have
>> shared their opinion about it. It is still in an exploratory phase:
>> looking what we have, what possibilities and needs are and choosing
>> goals and tools.
>>

>> I think, a next step should be  TO SET SOME CLEAR GOALS THAT CAN BE
>> ACCOMPLISHED WITHIN AN OVERSEEABLE TIMEFRAME and GET SOME PEOPLE
>> TOGETHER who want (and are able) to commit to such goals.

>>
>> The Joomla project consists of several parts, like the Platform
>> (framework) and the CMS. We also have several channels of
>> communication, like fora (mainly for users / integrators), etc. On
>> Google Groups we have 3 main lists, which are mainly for developers:
>> this Platform list, a CMS list and a general list. At the moment
>> there are several discussions on the general list mentioning vision,
>> leadership, setting goals, roadmaps, working groups and
>> organisation. So questions about it are vivid, but there is no
>> consensus on all points. That is also one of the unique aspects of
>> the Joomla projects: it is more organic and less centrally directed
>> than many other open source projects. Sometimes it is tiring,
>> sometimes there is more debate than code and it always takes some
>> time. But this typical process is also what makes it so unique. Most
>> of the time things happen, because some people do it (because they
>> just need it) and then they present it to the community.
>>
>> I want to do some small tasks in this group and help getting it on

>> the rails, but as Ive set other goals for the near future allready

>> (besides work, which is mainly custom Joomla components, mainly: to
>> at last make Doctrine easily available in Joomla,  refactor some
>> core classes with that and show the benefits of it for development),

>> I cannot commit to a big task here. There is however one thing Im

>> especially interested in: to use our current Joomla (Platform and
>> CMS) to develop some of the features we are talking about here. You
>> talk about Twig, but we have our own templating system and some
>> great frontend developers. Or should we integrate some Twig and what
>> you did with it into Joomla (some people have a Symfony-allergy
>> however ;-) ). Maybe we can even do something with Doctrine + Joomla

>> in this project; then Ill certainly participate more actively.

>>
>> What looks most promising to me at the moment are the points where
>> we can "embed" phpDocumentor in some Joomla-application (be it a
>> cms-component or platform-application) to add some extra features
>> like user comments to documentation that is generated via DocBlocks.
>> But that is just my idea, right now.
>>
>> - Herman
>>
>> On Tuesday, 26 February 2013 18:04:26 UTC+1, Mike van Riel wrote:
>>
>>> Allow me to elaborate a little on the current status of the
>>> project:
>>>
>>> phpDocumentor2 is a complete rebuild of phpDocumentor1 and as such
>>> has certain features the original had not and is missing some
>>> features that the original did have. This is the main reason it is
>>> still in an alpha state, the code is mature but so far we have
>>> reserved the right to make BC breaks (mainly within the code

>>> itself; the command line interface hasnt had a BC breaking change
>>> for many releases).
>>>
>>> At current I am in the middle of the last great push, which is a

>> [2].

>> For more options, visit https://groups.google.com/groups/opt_out

>> [3].

>>  
>>  
>
> --
> Chris Davenport
> Joomla Production Leadership Team
>

> --
> You received this message because you are subscribed to the Google
> Groups "Joomla! Platform Development" group.
> To unsubscribe from this group and stop receiving emails from it,
> send an email to joomla-dev-plat...@googlegroups.com.
> For more options, visit https://groups.google.com/groups/opt_out

> [6].
>
>
>
> Links:
> ------
> [1] http://docs.joomla.org
> [2] mailto:joomla-dev-platform%2Bunsu...@googlegroups.com
> [3] https://groups.google.com/groups/opt_out
> [4] http://api.joomla.org
> [5] mailto:herman...@gmail.com
> [6] https://groups.google.com/groups/opt_out

[Chris Davenport]

I'd love to look at that work.  Even if we don't use it for this particular project, I'm sure it will be of great interest in the Smart Search Working Group.

Chris.

--
You received this message because you are subscribed to the Google Groups "Joomla! Platform Development" group.
To unsubscribe from this group and stop receiving emails from it, send an email to joomla-dev-plat...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
 
 

[Chris Davenport]

Hi Mike,

That sounds very interesting.  I'm starting to look at the code now.  Is there some documentation on the Abstract Syntax Tree?  What would be the best starting point for creating a new Writer?

I'm actually quite happy about losing XML.  Parsing massive XML dumps is never fun.

All the best,
Chris.

send an email to joomla-dev-platform+unsub...@googlegroups.com

[2].

For more options, visit https://groups.google.com/groups/opt_out

[3].
 
 

--
Chris Davenport
Joomla Production Leadership Team

 --
 You received this message because you are subscribed to the Google
Groups "Joomla! Platform Development" group.
 To unsubscribe from this group and stop receiving emails from it,

send an email to joomla-dev-platform+unsub...@googlegroups.com.

 For more options, visit https://groups.google.com/groups/opt_out [6].



Links:
------
[1] http://docs.joomla.org
[2] mailto:joomla-dev-platform%2Bunsu...@googlegroups.com
[3] https://groups.google.com/groups/opt_out
[4] http://api.joomla.org
[5] mailto:herman...@gmail.com
[6] https://groups.google.com/groups/opt_out

--
You received this message because you are subscribed to the Google Groups "Joomla! Platform Development" group.

To unsubscribe from this group and stop receiving emails from it, send an email to joomla-dev-platform+unsub...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.

[Mike van Riel]

The Developer documentation is definitely not complete (which is
ironic, I know ;)).

The new AST and mechanics can be found in my serializing feature
branch[1]; what is needed
is the following:

1. A Cilex ServiceProvider[2] to register the Writer with the Writer
Collection to make it available
2. The Writer itself; which accepts a ProjectDescriptor (the root
object of the Object Graph) and the
transformation meta-data. A simple example would be our Checkstyle
writer[3].

The basic concept of a Writer is that it takes the AST Object Graph,
does some magic and voila: you
have an artifact. Where artifact can be a file, filled database or any
other deliverable.

The AST is represented by a series of Descriptors[4] where each
Descriptor represents a component in
your project and is linked. As such you can navigate it as you would
with a normal object tree.

One note: the Descriptors are not 100% stable as I am now working out
incrementally updating the tree
and removing stale items. Though I do not expect any exciting changes.

In case you are wondering; my current timetable for releasing this is
around the end of March. I need
to work out some details and write a backwards-compatibility layer for
the XSL writer and existing
templates.

[1]: https://github.com/mvriel/phpDocumentor2/blob/serializing
[2]:
https://github.com/mvriel/phpDocumentor2/blob/serializing/src/phpDocumentor/Plugin/Core/ServiceProvider.php
[3]:
https://github.com/mvriel/phpDocumentor2/blob/serializing/src/phpDocumentor/Plugin/Core/Transformer/Writer/Checkstyle.php
[4]:
https://github.com/mvriel/phpDocumentor2/tree/serializing/src/phpDocumentor/Descriptor

On 02.03.2013 01:54, Chris Davenport wrote:
> Hi Mike,
>

> That sounds very interesting.  Im starting to look at the code now. 

> Is there some documentation on the Abstract Syntax Tree?  What would
> be the best starting point for creating a new Writer?
>

> Im actually quite happy about losing XML.  Parsing massive XML dumps

> is never fun.
>
> All the best,
> Chris.
>

> On 1 March 2013 20:00, Mike van Riel <mike.v...@naenius.com [17]>

> wrote:
>
>> Hi Chris,
>>
>> It is trivial to write a Writer that writes the contents of the
>> Abstract Syntax Tree to a database or REST interface, so that is
>> definitely an option.
>>
>> I recommend using a Writer instead of replacing the serialization
>> process as it will help gain performance and benefit from

>> behaviours; that augment the object graph just in time.

>>
>> I am afraid I have to disappoint you with regards to the XML; it is
>> deprecated and will be replaced with a serialized object graph with
>> the next release.
>> For compatibility reasons I am writing a compatibility layer but
>> that
>> will be removed with version 2.1.
>>

>> Id like to point out, to provide a few options and insights, that

>> phpDocumentor2 is also capable of augmenting the Object Graph using
>> Behaviours (which are executed right before the transformation to
>> HTML).
>>

>> I am looking forward to your, and the other collaborators input.
>>
>> Mike

>>
>> On 27.02.2013 01 [14]:06, Chris Davenport wrote:
>>
>>> Hi Mike,
>>>
>>> My current thinking, obviously subject to change in the light of
>>> our
>>> conversations here, is that we would use a code analysis tool
>>> like
>>> phpDocumentor to generate a representation of the code that can
>>> be
>>> stored in a database (maybe from the XML that phpDocumentor
>>> generates?).  This data can then be augmented from other data
>>> sources
>>> such as Github, JoomlaCode, unit test results, other code
>>> analysis
>>> tools, etc.
>>>
>>> We can then build a variety of applications to query and extract
>>> data
>>> from that database.  Obviously, the traditional documentation
>>> website

>>> (like api.joomla.org [4] [4]) can be created with PHP-generated

>>> [5] [5]>

>>> wrote:
>>>
>>>> Hi Mike,
>>>>
>>>> There is no timetable, no clear goal and no committed working
>>>> group
>>>> (yet). Chris has done a lot to improve the wiki-documentation
>>>> on

>>>> docs.joomla.org [1] [1] over the years. One of the often heared

>>>> joomla-dev-plat...@googlegroups.com [2]

>>>> [2].
>>>>
>>>> For more options, visit
>>>> https://groups.google.com/groups/opt_out [3]
>>>> [3].
>>>>  
>>>>  
>>>
>>> --
>>> Chris Davenport
>>> Joomla Production Leadership Team
>>>
>>>  --
>>>  You received this message because you are subscribed to the
>>> Google
>>> Groups "Joomla! Platform Development" group.
>>>  To unsubscribe from this group and stop receiving emails from
>>> it,

>>> send an email to joomla-dev-plat...@googlegroups.com
>>> [6].
>>>  For more options, visit
>>> https://groups.google.com/groups/opt_out [7] [6].
>>>
>>> Links:
>>> ------
>>> [1] http://docs.joomla.org [8]
>>> [2] mailto:joomla-dev-platform%2Bunsu...@googlegroups.com [9]
>>> [3] https://groups.google.com/groups/opt_out [10]
>>> [4] http://api.joomla.org [11]
>>> [5] mailto:herman...@gmail.com [12]
>>> [6] https://groups.google.com/groups/opt_out [13]

>>
>> --
>> You received this message because you are subscribed to the Google
>> Groups "Joomla! Platform Development" group.
>> To unsubscribe from this group and stop receiving emails from it,

>> send an email to joomla-dev-plat...@googlegroups.com
>> [15].

>> For more options, visit https://groups.google.com/groups/opt_out

>> [16].

>
> --
> Chris Davenport
> Joomla Production Leadership Team
>
> --
> You received this message because you are subscribed to the Google
> Groups "Joomla! Platform Development" group.
> To unsubscribe from this group and stop receiving emails from it,

> send an email to joomla-dev-plat...@googlegroups.com.

> For more options, visit https://groups.google.com/groups/opt_out

> [18].

>
>
>
> Links:
> ------
> [1] http://docs.joomla.org
> [2] mailto:joomla-dev-platform%2Bunsu...@googlegroups.com
> [3] https://groups.google.com/groups/opt_out
> [4] http://api.joomla.org
> [5] mailto:herman...@gmail.com

> [6] mailto:joomla-dev-platform%2Bunsu...@googlegroups.com
> [7] https://groups.google.com/groups/opt_out
> [8] http://docs.joomla.org
> [9] mailto:joomla-dev-platform%252Buns...@googlegroups.com
> [10] https://groups.google.com/groups/opt_out
> [11] http://api.joomla.org
> [12] mailto:herman...@gmail.com
> [13] https://groups.google.com/groups/opt_out
> [14] http://webmail.web-oke.nl/tel:27.02.2013%2001
> [15] mailto:joomla-dev-platform%2Bunsu...@googlegroups.com
> [16] https://groups.google.com/groups/opt_out
> [17] mailto:mike.v...@naenius.com
> [18] https://groups.google.com/groups/opt_out

[Chris Davenport]

Thanks Mike.  Looks like I have some homework to do. :-)

Chris.

joomla-dev-platform+unsub...@googlegroups.com [2]

[2].

For more options, visit
https://groups.google.com/groups/opt_out [3]
[3].
 
 

--
Chris Davenport
Joomla Production Leadership Team

 --
 You received this message because you are subscribed to the
Google
Groups "Joomla! Platform Development" group.
 To unsubscribe from this group and stop receiving emails from
it,

send an email to joomla-dev-platform+unsub...@googlegroups.com

[6].
 For more options, visit
https://groups.google.com/groups/opt_out [7] [6].

Links:
------
[1] http://docs.joomla.org [8]
[2] mailto:joomla-dev-platform%2Bunsu...@googlegroups.com [9]
[3] https://groups.google.com/groups/opt_out [10]
[4] http://api.joomla.org [11]
[5] mailto:herman...@gmail.com [12]
[6] https://groups.google.com/groups/opt_out [13]

--
You received this message because you are subscribed to the Google
Groups "Joomla! Platform Development" group.
To unsubscribe from this group and stop receiving emails from it,

send an email to joomla-dev-platform+unsub...@googlegroups.com

[15].

For more options, visit https://groups.google.com/groups/opt_out

[16].

--
Chris Davenport
Joomla Production Leadership Team

 --
 You received this message because you are subscribed to the Google
Groups "Joomla! Platform Development" group.
 To unsubscribe from this group and stop receiving emails from it,

send an email to joomla-dev-platform+unsub...@googlegroups.com.

 For more options, visit https://groups.google.com/groups/opt_out

[18].

Links:
------
[1] http://docs.joomla.org
[2] mailto:joomla-dev-platform%2Bunsu...@googlegroups.com
[3] https://groups.google.com/groups/opt_out
[4] http://api.joomla.org
[5] mailto:herman...@gmail.com

[6] mailto:joomla-dev-platform%2Bunsu...@googlegroups.com
[7] https://groups.google.com/groups/opt_out
[8] http://docs.joomla.org

[9] mailto:joomla-dev-platform%252Bunsubscribe@googlegroups.com

[10] https://groups.google.com/groups/opt_out
[11] http://api.joomla.org
[12] mailto:herman...@gmail.com
[13] https://groups.google.com/groups/opt_out
[14] http://webmail.web-oke.nl/tel:27.02.2013%2001
[15] mailto:joomla-dev-platform%2Bunsu...@googlegroups.com
[16] https://groups.google.com/groups/opt_out

[17] mailto:mike.vanriel@naenius.com
[18] https://groups.google.com/groups/opt_out

--
You received this message because you are subscribed to the Google Groups "Joomla! Platform Development" group.

To unsubscribe from this group and stop receiving emails from it, send an email to joomla-dev-platform+unsub...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.

[Mike van Riel]

If you have any questions or encounter (blocking) issues (except that
it isn't released yet ;)),
let me know. It is via the feedback of the community that Chuck and I
can deliver the most value
with regards to documentation.

As such, it is all very much appreciated.

On 02.03.2013 12:41, Chris Davenport wrote:
> Thanks Mike.  Looks like I have some homework to do. :-)
>
> Chris.
>

> On 2 March 2013 06:53, Mike van Riel <mike.v...@naenius.com [44]>

>> [1]: https://github.com/mvriel/phpDocumentor2/blob/serializing [38]
>> [2]:
>>
>
> https://github.com/mvriel/phpDocumentor2/blob/serializing/src/phpDocumentor/Plugin/Core/ServiceProvider.php
>> [39]
>> [3]:
>>
>
> https://github.com/mvriel/phpDocumentor2/blob/serializing/src/phpDocumentor/Plugin/Core/Transformer/Writer/Checkstyle.php
>> [40]
>> [4]:
>>
>
> https://github.com/mvriel/phpDocumentor2/tree/serializing/src/phpDocumentor/Descriptor
>> [41]

>>
>> On 02.03.2013 01:54, Chris Davenport wrote:
>>
>>> Hi Mike,
>>>
>>> That sounds very interesting.  Im starting to look at the code
>>> now. 
>>>
>>> Is there some documentation on the Abstract Syntax Tree?  What
>>> would
>>> be the best starting point for creating a new Writer?
>>>
>>> Im actually quite happy about losing XML.  Parsing massive XML
>>> dumps
>>> is never fun.
>>>
>>> All the best,
>>> Chris.
>>>
>>> On 1 March 2013 20:00, Mike van Riel <mike.v...@naenius.com

>>> [17] [17]>

>>>>> (like api.joomla.org [4] [4] [4]) can be created with

>>>>>> docs.joomla.org [1] [1] [1] over the years. One of the

>>>>>> joomla-dev-plat...@googlegroups.com [2] [2]

>>>>>> [2].
>>>>>>
>>>>>> For more options, visit
>>>>>> https://groups.google.com/groups/opt_out [3] [3]
>>>>>> [3].
>>>>>>  
>>>>>>  
>>>>>
>>>>> --
>>>>> Chris Davenport
>>>>> Joomla Production Leadership Team
>>>>>
>>>>>  --
>>>>>  You received this message because you are subscribed to the
>>>>> Google
>>>>> Groups "Joomla! Platform Development" group.
>>>>>  To unsubscribe from this group and stop receiving emails
>>>>> from
>>>>> it,
>>>>> send an email to

>>>>> joomla-dev-plat...@googlegroups.com [6]

>>>>> [6].
>>>>>  For more options, visit

>>>>> https://groups.google.com/groups/opt_out [7] [7] [6].
>>>>>
>>>>> Links:
>>>>> ------
>>>>> [1] http://docs.joomla.org [8] [8]
>>>>> [2] mailto:joomla-dev-platform%2Bunsu...@googlegroups.com
>>>>> [9] [9]
>>>>> [3] https://groups.google.com/groups/opt_out [10] [10]
>>>>> [4] http://api.joomla.org [11] [11]
>>>>> [5] mailto:herman...@gmail.com [12] [12]
>>>>> [6] https://groups.google.com/groups/opt_out [13] [13]

>>>>
>>>> --
>>>> You received this message because you are subscribed to the
>>>> Google
>>>> Groups "Joomla! Platform Development" group.
>>>> To unsubscribe from this group and stop receiving emails from
>>>> it,
>>>> send an email to

>>>> joomla-dev-plat...@googlegroups.com [15]

>>>> [15].
>>>>
>>>> For more options, visit
>>>> https://groups.google.com/groups/opt_out [16]
>>>> [16].
>>>
>>> --
>>> Chris Davenport
>>> Joomla Production Leadership Team
>>>
>>>  --
>>>  You received this message because you are subscribed to the
>>> Google
>>> Groups "Joomla! Platform Development" group.
>>>  To unsubscribe from this group and stop receiving emails from
>>> it,

>>> send an email to joomla-dev-plat...@googlegroups.com
>>> [18].
>>>  For more options, visit
>>> https://groups.google.com/groups/opt_out [19]
>>> [18].
>>>
>>> Links:
>>> ------
>>> [1] http://docs.joomla.org [20]
>>> [2] mailto:joomla-dev-platform%2Bunsu...@googlegroups.com
>>> [21]
>>> [3] https://groups.google.com/groups/opt_out [22]
>>> [4] http://api.joomla.org [23]
>>> [5] mailto:herman...@gmail.com [24]
>>> [6] mailto:joomla-dev-platform%2Bunsu...@googlegroups.com
>>> [25]
>>> [7] https://groups.google.com/groups/opt_out [26]
>>> [8] http://docs.joomla.org [27]
>>> [9] mailto:joomla-dev-platform%252Buns...@googlegroups.com
>>> [28]
>>> [10] https://groups.google.com/groups/opt_out [29]
>>> [11] http://api.joomla.org [30]
>>> [12] mailto:herman...@gmail.com [31]
>>> [13] https://groups.google.com/groups/opt_out [32]
>>> [14] http://webmail.web-oke.nl/tel:27.02.2013%2001 [33]
>>> [15] mailto:joomla-dev-platform%2Bunsu...@googlegroups.com
>>> [34]
>>> [16] https://groups.google.com/groups/opt_out [35]
>>> [17] mailto:mike.v...@naenius.com [36]
>>> [18] https://groups.google.com/groups/opt_out [37]

>>
>> --
>> You received this message because you are subscribed to the Google
>> Groups "Joomla! Platform Development" group.
>> To unsubscribe from this group and stop receiving emails from it,

>> send an email to joomla-dev-plat...@googlegroups.com
>> [42].

>> For more options, visit https://groups.google.com/groups/opt_out

>> [43].

>
> --
> Chris Davenport
> Joomla Production Leadership Team
>
> --
> You received this message because you are subscribed to the Google
> Groups "Joomla! Platform Development" group.
> To unsubscribe from this group and stop receiving emails from it,

> send an email to joomla-dev-plat...@googlegroups.com.

> For more options, visit https://groups.google.com/groups/opt_out

> [45].

>
>
>
> Links:
> ------
> [1] http://docs.joomla.org
> [2] mailto:joomla-dev-platform%2Bunsu...@googlegroups.com
> [3] https://groups.google.com/groups/opt_out
> [4] http://api.joomla.org
> [5] mailto:herman...@gmail.com
> [6] mailto:joomla-dev-platform%2Bunsu...@googlegroups.com
> [7] https://groups.google.com/groups/opt_out
> [8] http://docs.joomla.org

> [9] mailto:joomla-dev-platform%252Buns...@googlegroups.com

> [10] https://groups.google.com/groups/opt_out
> [11] http://api.joomla.org
> [12] mailto:herman...@gmail.com
> [13] https://groups.google.com/groups/opt_out
> [14] http://webmail.web-oke.nl/tel:27.02.2013%2001
> [15] mailto:joomla-dev-platform%2Bunsu...@googlegroups.com
> [16] https://groups.google.com/groups/opt_out

> [17] mailto:mike.v...@naenius.com
> [18] mailto:joomla-dev-platform%2Bunsu...@googlegroups.com
> [19] https://groups.google.com/groups/opt_out
> [20] http://docs.joomla.org
> [21] mailto:joomla-dev-platform%252Buns...@googlegroups.com
> [22] https://groups.google.com/groups/opt_out
> [23] http://api.joomla.org
> [24] mailto:herman...@gmail.com
> [25] mailto:joomla-dev-platform%252Buns...@googlegroups.com
> [26] https://groups.google.com/groups/opt_out
> [27] http://docs.joomla.org
> [28] mailto:joomla-dev-platform%25252Bun...@googlegroups.com
> [29] https://groups.google.com/groups/opt_out
> [30] http://api.joomla.org
> [31] mailto:herman...@gmail.com
> [32] https://groups.google.com/groups/opt_out
> [33] http://webmail.web-oke.nl/tel:27.02.2013%2001
> [34] mailto:joomla-dev-platform%252Buns...@googlegroups.com
> [35] https://groups.google.com/groups/opt_out
> [36] mailto:mike.v...@naenius.com
> [37] https://groups.google.com/groups/opt_out
> [38] https://github.com/mvriel/phpDocumentor2/blob/serializing
> [39]
>
> https://github.com/mvriel/phpDocumentor2/blob/serializing/src/phpDocumentor/Plugin/Core/ServiceProvider.php
> [40]
>
> https://github.com/mvriel/phpDocumentor2/blob/serializing/src/phpDocumentor/Plugin/Core/Transformer/Writer/Checkstyle.php
> [41]
>
> https://github.com/mvriel/phpDocumentor2/tree/serializing/src/phpDocumentor/Descriptor
> [42] mailto:joomla-dev-platform%2Bunsu...@googlegroups.com
> [43] https://groups.google.com/groups/opt_out
> [44] mailto:mike.v...@naenius.com
> [45] https://groups.google.com/groups/opt_out