On Tue, May 19, 2009 at 9:56 PM, Hadrian Zbarcea <hzbar...@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 >>> <ch...@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
