Yes, karaf uses scaml, scalate to generate the html, pdf documents
On Thu, Apr 21, 2011 at 12:44 PM, Claus Ibsen <claus.ib...@gmail.com> wrote:
> 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/
>
