camel-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Claus Ibsen <claus.ib...@gmail.com>
Subject Re: Documenting the Camel DSL
Date Sat, 23 May 2009 08:18:42 GMT
On Tue, May 19, 2009 at 9:56 PM, Hadrian Zbarcea <hzbarcea@gmail.com> wrote:
> Hi Christian,
>
> You have a point there :).
>
> I personally like the wiki as a documentation tool and I like even more your
> offer to help :).  You have enough karma to start this on the wiki.
Yeah there is a DSL page that can be used as starting point. Or create
a new wiki page.

Basically most of the DSL is in the ProcessorDefiniton class, that
covers 80+% of the DSL we have.
Then there are some specific DSL per type that is on the xxxDefinition.



>
> Thanks
> Hadrian
>
>
> On May 19, 2009, at 3:33 PM, Christian Schneider wrote:
>
>> Hi Claus,
>>
>> some time ago I thought the same as you. That api documentation should
>> come from javadoc and a tool should make html out of it.
>> My experience with this approach is quite bad though. The Javadoc html is
>> quite ugly and people quite seldomly really use it. The xsds currently also
>> do not include the javadoc. There is not much tooling around and creating
>> the tooling normally gets low priority so the effect is most times bad
>> documentation in the end.
>>
>> So on the one hand I think the javadoc should be kept in good shape so
>> people that use the java api can read some documentation in their ide. On
>> the other hand it is quite unattractive to improve the javadoc.
>> You have to check out the code change the java code, make sure it still
>> builds and send a patch to the committers. If you are a committer it is a
>> little easier as you probably have the code ready already. Still I have the
>> feeling that people outside the commiters will not help much with the
>> documentation.
>>
>> On the other hand there is a really good example of api documentation on
>> the web. The php documentation (e.g.
>> http://www.php.net/manual/en/function.str-getcsv.php).
>> There is a part of the documentation that is written by the developers and
>> then people can comment and discuss below. I have found some of the best
>> hints in these comments. Perhaps camel could do such a thing too. The fixed
>> part could be extracted from javadoc. Then there should be the possibility
>> to add comments to the api function. The best thing would be to even not
>> require people to have to create a user for the wiki. I could imagine that
>> there would be quite a lot of help from the community. In any case the java
>> documentation for an api function should contain a link to the wiki page
>> where people can also read the community comments.
>>
>> Apart from this I think we should not wait till the tooling is written. I
>> would suggest to start documenting the API in the wiki without any tooling.
>> Later when the tooling is finished we could consolidate it. The big
>> advantage would be that the camel user see improved documentation from the
>> start.  The tooling solution can take a long time to do and in the mean time
>> users will see absolutely no improvement. In any way I would volunteer to
>> help a bit documenting the functions I use whatever solution you choose.
>>
>> Greetings
>>
>> Christian
>>
>>
>>
>>
>> Claus Ibsen schrieb:
>>>
>>> On Sun, May 17, 2009 at 11:16 AM, Christian Schneider
>>> <chris@die-schneider.net> wrote:
>>>
>>>> Hi,
>>>>
>>>> the current documentation of camel lacks one very important part: The
>>>> Camel
>>>> DSL. I have not found an index and detail pages about the different DSL
>>>> functions.
>>>> Is there any documentation already and I simply did not find it?
>>>>
>>>> If not I would like to help in building some documentation. The question
>>>> is
>>>> what would be a good structure?
>>>> I could imagine having one main page that holds an alphabetic and or
>>>> categorised list of DSL functions. Then below there could be one page
>>>> per
>>>> function.
>>>> The categories could be done via labels so the lists on the index page
>>>> could
>>>> be kept in sync automatically.
>>>>
>>>> Any ideas about this?
>>>>
>>> Hi
>>>
>>> We have debated this from time to time. The concensus is that we would
>>> like this to be automated by scripts/tooling.
>>> It would be impossible to keep the confluence wiki updated (I dislike
>>> this wiki as its online based only) with all the DSL.
>>>
>>> What would be better is that we could reuse the javadoc we have on the
>>> DSL in the code and use tooling to extract that.
>>>
>>> For starters it would be best if the tooling could enhance the
>>> camel-spring.xsd generator to add <xsd:documentation> (I think the tag
>>> is named) based on the model javadoc. Then we could improve the model
>>> javadoc. Also each JAXB @ annotation we have for the model could be
>>> documented as well and the tooling being able to slurp that as well.
>>>
>>> Then we will have nice documentation in the XSD.
>>> This XSD can maybe then be transformed into some HTML or whatever that
>>> can be used in the wiki documentation.
>>>
>>> However the XSD would be the best as it allows 3rd party visual
>>> tooling to leverage this documentation, that is also best suited for
>>> end users that uses these tools and are on a more beginner level and
>>> thus requires better documentation.
>>>
>>> There is ticket about this already in the Camel JIRA: CAMEL-632
>>>
>>>
>>>
>>>
>>>> Greetings
>>>>
>>>> Christian
>>>>
>>>> --
>>>>
>>>> Christian Schneider
>>>> ---
>>>> http://www.liquid-reality.de
>>>>
>>>>
>>>>
>>>
>>>
>>>
>>>
>>
>>
>> --
>>
>> Christian Schneider
>> ---
>> http://www.liquid-reality.de
>>
>
>



-- 
Claus Ibsen
Apache Camel Committer

Open Source Integration: http://fusesource.com
Blog: http://davsclaus.blogspot.com/
Twitter: http://twitter.com/davsclaus

Mime
View raw message