camel-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Christian Schneider <ch...@die-schneider.net>
Subject Re: Documenting the Camel DSL
Date Mon, 08 Jun 2009 22:09:01 GMT
Hi Claus,

I did not really understand your comment 1). Why do you think that we 
have to micro manage the documentation? Is it because both javadoc and 
wiki have to be written?
This of course is an issue but I could imagine it can be kept in sync. 
Apart from this I do not see that much micro management in the approach. 
To add documentation to one function you simply add a page nothing else 
has to be done.

About 2) you are right. My examples are not very good but they are 
mainly thought as a starting point. Every one with access to the wiki 
can add examples or refine the existing. I mainly wanted to show how the 
wiki template looks for two functions to give a better base for 
discussion. The wiki lives from people helping to improve it. But before 
we write many pages it is a good idea to reach some consensus about the 
structure as it is a lot of work to adapt the structure at a later 
point. It would be great if you could improve the examples to show more 
context.

About 4) yes. The EIP patterns are already explained very well though 
they lack a good reference. I think in some way they are the oposite of 
what you did not like in my approach. They have really good examples but 
no reference of the parameters. I think the best approach should have 
both. Each function should have a thorough refrence and good examples. 
Of course I do not intend to write new pages for the EIP patterns. 
Perhaps we can leave them completely untouched at the moment and 
concentrate on the rest of the functions. At a later point it could be a 
good idea to bring some more structure into the eip patterns.

About 5). I am not sure if having only one sample is enough but it would 
surely safe us a lot of work writing the examples.

Greetings

Christian

Claus Ibsen schrieb:
>
> Hi
>
> We really appreciate the effort to document the DSL.
>
> Looking at the current pages done so far I have the following comments:
>
> 1)
> Overall I do not think trying to structure the documentation so
> rigiours is feasible.
> It should be fast and easy to add the documentation. Having to micro
> manage it is bound to people not wanting to do it.
>
> 2)
> The examples is poor. What is needed is a good context where to use
> it. What is there currently is just the single DSL, as a kind of
> syntax example.
> That dont bring much to the table.
>
> You dont get the clue that from DSL is used as input to a route as a
> the event driven consumer.
> And that the convert body to DSL is used in the middle of a route, for
> instance to load the file content, or force convertions to a
> particular type.
> And there should be a link to the existing type converter page so
> people can read more about it.
>
> And so on. Better examples is better than structure and tables.
>
> 3)
> Also more details what and why we have this DSL.
>
> 4)
> And for the EIP patterns we should of course just link directly to
> their existing documentation, to avoid repeating yourself.
>
> 5)
> Java vs. Spring. Often having a sample in either one is sufficient. It
> only makes sense to document the Spring and Java when the Spring is
> particual different such as the error handler. Or for some more
> complex DSL such as the splitter, aggregator and whatnot.
>
>
>
>
>   
>> Greetings
>>
>> Christian
>>
>> Claus Ibsen schrieb:
>>     
>>> 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.
>>>
>>>
>>>
>>>       
>>     
>
>
>
>   


Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message