On Thu, Apr 21, 2011 at 12:40 PM, Charles Moulliard
<cmoulli...@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.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/
