camel-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Charles Moulliard <cmoulli...@gmail.com>
Subject Re: Suggestion : Add Annotations within Camel components to document URIs keys
Date Thu, 21 Apr 2011 12:01:28 GMT
Yes, karaf uses scaml, scalate to generate the html, pdf documents

On Thu, Apr 21, 2011 at 12:44 PM, Claus Ibsen <claus.ibsen@gmail.com> wrote:
> On Thu, Apr 21, 2011 at 12:40 PM, Charles Moulliard
> <cmoulliard@gmail.com> wrote:
>> Hey Claus, you know me, I don' t want to reinvent the wheel and prefer
>> to capitalize on existing tools, frameworks.
>>
>> If I we can use the JAXB annotation, let's go for it, nevertheless,
>> I'm a bit skeptical and not sure if it will be possible to document
>> what I want to do.
>>
>> Remark : We could reuse the karaf-maven-plugin generating a
>> docbook.xml file from karaf command annoted class ;-)
>> Here is an example
>>
>> /**
>>  * Creates a new user in the active realm/module.
>>  *
>>  * @author iocanel
>>  */
>> @Command(scope = "jaas", name = "useradd", description = "Add a user.")
>> public class UserAddCommand extends JaasCommandSupport {
>>
>>    @Argument(index = 0, name = "username", description = "User Name",
>> required = true, multiValued = false)
>>    private String username;
>>
>>    @Argument(index = 1, name = "password", description = "Password",
>> required = true, multiValued = false)
>>    private String password;
>>
>>
>
> Yeah you are using Scalete for generating the web site?
>
> So I think we should pickup this idea when we migrate Camel to
> scalate. Then we should be able to generate the website likewise,
> which would grab documentation from those annotations.
>
>
>
>>
>> On Thu, Apr 21, 2011 at 12:29 PM, Claus Ibsen <claus.ibsen@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
>>> <cmoulliard@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.ibsen@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.ibsen@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
>>>>>> <cmoulliard@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.ibsen@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 <cmoulliard@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 <hzbarcea@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
<emjohnson@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
>>>>>>>>>>>> <cmoulliard@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: emjohnson@fusesource.com
>>>>>>>>>>>> Blog: http://documentingit.blogspot.com/
>>>>>>>>>>>> Twitter: finnmccumial
>>>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>>> --
>>>>>>>> Claus Ibsen
>>>>>>>> -----------------
>>>>>>>> FuseSource
>>>>>>>> Email: cibsen@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: cibsen@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: cibsen@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: cibsen@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: cibsen@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/
>

Mime
View raw message