Also its in fact not only Camel components that would be nice to have
documentation in the source code, but auto synced in the apache camel
web pages. It also applies for the EIP patterns as they also have
options. And to some extend Data Formats as well.
We have 2 places where the documentation from the source code would be handy
1) Since the EIP is part of the XML DSL it would be nice to have it
documented in there as well (hence that JAXB annotation would be
great).
2) Components, EIPs, Data Formats in the Apache Camel web pages
(currently confluence).
Today we have the following solution only
Ad 1) None
Ad 2) Using the SNIPPET tag (only works with confluence).
If we go about adding our own @Document annotation as suggested, then
it benefits tooling as well as they would be able to tap into the
annotation and grab the documentation text. So the idea is nice.
However its an universal problem and would be great with a annotation
from the JDK.
To have the Apache web site being able to tap into the @Document
annotation it would have to grab the JAR from the maven repo and tap
into the JAR archive to find the annotations to grab the documentation
text. If that is possible, then that would be great as we would have 1
annotation supporting both the Apache camel web site, and 3rd party
tooling as well.
I am sure Oracle takes forever to decide to add that @ annotation to
JAXB so it may be worth wile to continue and look for a general
solution or consider adding the annotation to Camel.
On Thu, Apr 21, 2011 at 12:29 PM, Claus Ibsen <claus.ib...@gmail.com> wrote:
> If there is a JAXBDocument annotation in the JDK then we can use that
> instead of inventing our own annotation.
>
> And frankly its an universal problem. So there must be better
> solutions out there than adding a new annotation to Camel, and
> building our own tool to parse the source code and extract the
> documentation, and how to get that injected into Confluence Wiki. (Or
> in the future scalate).
>
>
>
> On Thu, Apr 21, 2011 at 11:46 AM, Charles Moulliard
> <cmoulli...@gmail.com> wrote:
>> Hmmm. We do not use JAXB Annotations into component class of camel
>>
>> **
>> * FTP Component
>> */
>> public class FtpComponent extends RemoteFileComponent<FTPFile> {
>>
>> public FtpComponent() {
>> }
>>
>> public FtpComponent(CamelContext context) {
>> super(context);
>> }
>>
>> So How could it be possible to use what you suggest with jaxb
>> annotation --> xchema --> Doc ?
>>
>> On Thu, Apr 21, 2011 at 10:17 AM, Claus Ibsen <claus.ib...@gmail.com> wrote:
>>> And we also today have the SNIPPET tag we can use with the confluence
>>> wiki. So you can add those wiki tags in the javadoc and have the code
>>> auto documented.
>>>
>>> But thats not the best idea as we would like to migrate the
>>> documentation to scalate like SMX / Karaf and other Apache projects.
>>>
>>>
>>> On Thu, Apr 21, 2011 at 10:16 AM, Claus Ibsen <claus.ib...@gmail.com> wrote:
>>>> Hi
>>>>
>>>>
>>>> This is the Oracle ticket
>>>> http://java.net/jira/browse/JAXB-273
>>>>
>>>> And this was from the original request (they closed this as a
>>>> duplicate of that above)
>>>> http://java.net/jira/browse/JAXB-369
>>>>
>>>> And this is the Camel ticket
>>>> https://issues.apache.org/jira/browse/CAMEL-632
>>>>
>>>>
>>>> In camel-spring pom.xml there is an ANT task that invokes the JAXB
>>>> tooling to generate the schema from the camel-core source code. Its
>>>> standard JAXB from the JDK so there is nothing special Camel about
>>>> that. In the old days we used to have a patched JAXB JAR due many bugs
>>>> in the JAXB from the JDK. But they have fixed those bugs now.
>>>>
>>>>
>>>> On Thu, Apr 21, 2011 at 10:05 AM, Charles Moulliard
>>>> <cmoulli...@gmail.com> wrote:
>>>>> Can you provide info about what Oracle plan to do that and how we
>>>>> generate XSD schema from JAXB now ?
>>>>> Many thanks in advance,
>>>>>
>>>>> Regards,
>>>>>
>>>>> Charles
>>>>>
>>>>> On Thu, Apr 21, 2011 at 9:33 AM, Claus Ibsen <claus.ib...@gmail.com>
>>>>> wrote:
>>>>>> JAXB has annotations to generate the XSD schema. There is a RFE at
>>>>>> Oracle to add an annotation to provide documentation. If there was
>>>>>> such an annotation we could use that in the model classes and have
>>>>>> documentation in the XSD as well, which tooling could use (eg in
>>>>>> Eclipse etc.) So I would prefer to push in that direction to have
>>>>>> Oracle add that annotation.
>>>>>>
>>>>>> Alternatively is to try to hack or add a 2nd pass on the XSD schema to
>>>>>> inject the documentation ourself. We have a JIRA ticket at Apache
>>>>>> Camel about this. Its a rather old ticket so it has a low number.
>>>>>>
>>>>>> And for regular java code, there is already documentation available
>>>>>> which is JavaDoc.
>>>>>>
>>>>>> On Wed, Apr 20, 2011 at 6:54 PM, Charles Moulliard
>>>>>> <cmoulli...@gmail.com> wrote:
>>>>>>> @Component is the annotation used by Spring, this is why I suggested
>>>>>>> @CamelComponent ...
>>>>>>>
>>>>>>> Alternative could be @IntegrationComponent
>>>>>>>
>>>>>>> Remark : We could use what has been developed into the
>>>>>>> karaf-maven-plugin to generate Docbook.xml doc from annoted classes.
>>>>>>> The mojo plugin of karaf is simple as it generate using java.io.writer
>>>>>>> the output but effort will be probably less than using a templating
>>>>>>> engine like velocity, freemarker
>>>>>>>
>>>>>>> On Wed, Apr 20, 2011 at 6:43 PM, Hadrian Zbarcea <hzbar...@gmail.com>
>>>>>>> wrote:
>>>>>>>> Since the annotation will be an in a o.a.camel package, I would drop
>>>>>>>> the redundant Camel prefix too.
>>>>>>>>
>>>>>>>> Hadrian
>>>>>>>>
>>>>>>>> On Apr 20, 2011, at 12:38 PM, Charles Moulliard wrote:
>>>>>>>>
>>>>>>>>> Additional information like isTransactional = True, False, type =
>>>>>>>>> "ProducerOnly, ConsumerOnly,Both" could be added
>>>>>>>>>
>>>>>>>>> @CamelComponent(name="","description="",example="", pageUrl="",
>>>>>>>>> isTransactional="true/false", type="ProducerOnly, ConsumerOnly,Both")
>>>>>>>>> public class Component {
>>>>>>>>>
>>>>>>>>>
>>>>>>>>> On Wed, Apr 20, 2011 at 5:05 PM, Eric Johnson
>>>>>>>>> <emjohn...@fusesource.com> wrote:
>>>>>>>>>> It may be a bit of a "new puppy" item, but I think it is a great
>>>>>>>>>> idea.
>>>>>>>>>> Self documenting code is always a good idea.
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>> On Wed, Apr 20, 2011 at 10:50 AM, Charles Moulliard
>>>>>>>>>> <cmoulli...@gmail.com> wrote:
>>>>>>>>>>> Hi,
>>>>>>>>>>>
>>>>>>>>>>> I would like to suggest that we add annotation to document the
>>>>>>>>>>> properties of the Camel Component class which are used customise the
>>>>>>>>>>> component according to the keys defined into the URIs.
>>>>>>>>>>>
>>>>>>>>>>> What do you about that ?
>>>>>>>>>>>
>>>>>>>>>>> idea
>>>>>>>>>>>
>>>>>>>>>>> URI => componentName:property1:property2....?key1=value&key2=value
>>>>>>>>>>> .....
>>>>>>>>>>>
>>>>>>>>>>> @CamelComponent(name="","description="",example="", pageUrl="")
>>>>>>>>>>> public class Component {
>>>>>>>>>>>
>>>>>>>>>>> @CamelComponentKey(name="", description="", type="boolean,
>>>>>>>>>>> string")
>>>>>>>>>>> String key1;
>>>>>>>>>>>
>>>>>>>>>>> @CamelComponentKey(name="", description="", type="boolean,
>>>>>>>>>>> string")
>>>>>>>>>>> String key2;
>>>>>>>>>>>
>>>>>>>>>>> String key3;
>>>>>>>>>>> ...
>>>>>>>>>>> }
>>>>>>>>>>>
>>>>>>>>>>> We could use those annotations to document camel component (when
>>>>>>>>>>> generating pdf, html, ...) or provide URI definition when using
>>>>>>>>>>> autocompletion in Eclipse, IntelliJ, ....
>>>>>>>>>>>
>>>>>>>>>>> Regards,
>>>>>>>>>>>
>>>>>>>>>>> Charles Moulliard
>>>>>>>>>>>
>>>>>>>>>>> Sr. Principal Solution Architect - FuseSource
>>>>>>>>>>> Apache Committer
>>>>>>>>>>>
>>>>>>>>>>> Blog : http://cmoulliard.blogspot.com
>>>>>>>>>>> Twitter : http://twitter.com/cmoulliard
>>>>>>>>>>> Linkedin : http://www.linkedin.com/in/charlesmoulliard
>>>>>>>>>>> Skype: cmoulliard
>>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>> --
>>>>>>>>>> Principle Technical Writer
>>>>>>>>>> FuseSource
>>>>>>>>>> Phone: (781) 280-4174
>>>>>>>>>> E-Mail: emjohn...@fusesource.com
>>>>>>>>>> Blog: http://documentingit.blogspot.com/
>>>>>>>>>> Twitter: finnmccumial
>>>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>>
>>>>>>
>>>>>>
>>>>>>
>>>>>> --
>>>>>> Claus Ibsen
>>>>>> -----------------
>>>>>> FuseSource
>>>>>> Email: cib...@fusesource.com
>>>>>> Web: http://fusesource.com
>>>>>> CamelOne 2011: http://fusesource.com/camelone2011/
>>>>>> Twitter: davsclaus
>>>>>> Blog: http://davsclaus.blogspot.com/
>>>>>> Author of Camel in Action: http://www.manning.com/ibsen/
>>>>>>
>>>>>
>>>>
>>>>
>>>>
>>>> --
>>>> Claus Ibsen
>>>> -----------------
>>>> FuseSource
>>>> Email: cib...@fusesource.com
>>>> Web: http://fusesource.com
>>>> CamelOne 2011: http://fusesource.com/camelone2011/
>>>> Twitter: davsclaus
>>>> Blog: http://davsclaus.blogspot.com/
>>>> Author of Camel in Action: http://www.manning.com/ibsen/
>>>>
>>>
>>>
>>>
>>> --
>>> Claus Ibsen
>>> -----------------
>>> FuseSource
>>> Email: cib...@fusesource.com
>>> Web: http://fusesource.com
>>> CamelOne 2011: http://fusesource.com/camelone2011/
>>> Twitter: davsclaus
>>> Blog: http://davsclaus.blogspot.com/
>>> Author of Camel in Action: http://www.manning.com/ibsen/
>>>
>>
>
>
>
> --
> Claus Ibsen
> -----------------
> FuseSource
> Email: cib...@fusesource.com
> Web: http://fusesource.com
> CamelOne 2011: http://fusesource.com/camelone2011/
> Twitter: davsclaus
> Blog: http://davsclaus.blogspot.com/
> Author of Camel in Action: http://www.manning.com/ibsen/
>
--
Claus Ibsen
-----------------
FuseSource
Email: cib...@fusesource.com
Web: http://fusesource.com
CamelOne 2011: http://fusesource.com/camelone2011/
Twitter: davsclaus
Blog: http://davsclaus.blogspot.com/
Author of Camel in Action: http://www.manning.com/ibsen/
