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;
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/
>
