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.
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
