camel-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From James Strachan <james.strac...@gmail.com>
Subject Re: improving Endpoint documentation and tooling
Date Tue, 23 Apr 2013 10:03:21 GMT
I've added a couple of wiki pages to help describe the new capabilities:

the endpoint annotations:
https://cwiki.apache.org/confluence/display/CAMEL/Endpoint+Annotations

the ComponentConfiguration API:
https://cwiki.apache.org/confluence/display/CAMEL/ComponentConfiguration


On 23 April 2013 09:47, James Strachan <james.strachan@gmail.com> wrote:
> Endpoint documentation is manually created on the wiki which is quite
> error prone; plus the wiki page has to then cope with every version of
> Camel we release and is very easy to get stale and incorrect - and
> with all the 'since version X' text its confusing for users.
>
> Additionally its hard for tool providers to create user interfaces to
> let users create and edit endpoint parameters in IDEs and web
> consoles.
>
> To help address this we now have:
>
> * a maven plugin which can automaticaly generate HTML documentation
> for how to configure an endpoint as part of the maven site, if you add
> a few annotations into your Endpoint code.
> https://issues.apache.org/jira/browse/CAMEL-6304
>
> If you grab the latest code, do a build, then run:
>
>     cd camel-core
>     open target/classes/org/apache/camel/component/timer.html
>
> you'll see the generated HTML docuemtnation for the timer endpoint.
> This is then included by default in the jar; so folks can easily get
> the documentation for the components on their classpath.
>
> Or run:
>
>     mvn site
>
> and you'll see the Camel Endpoints page generated in the maven site reports.
>
> To get an idea of the annotations, here's the Timer endpoint
> https://github.com/apache/camel/blob/trunk/camel-core/src/main/java/org/apache/camel/component/timer/TimerEndpoint.java#L40
>
> notice the use of @UriEndpoint on the endpoint (which links to the
> consumer also) then the @UriParam for any URI parameter. (We could in
> the future use @UriParam on setters too; for now only field annotation
> is supported).
>
>
> * a ComponentConfiguration API so that tools can introspect components
> to discover the available parameters and their types and metadata;
> then create/edit either URIs or Endpoints directly
> https://issues.apache.org/jira/browse/CAMEL-6306
>
> The nice thing about the new ComponentConfiguration API is that a tool
> can start from scratch; you don't need to create an endpoint first
> from a URI before you can configure things like with
> EndpointConfiguration. Also the ComponentConfiguration API is
> introspectable; you can ask for all the available
> ParameterConfiguration objects (with the name and their types and any
> associated metadata such as if Bean Validation API annotations are
> used etc).
>
> So today all Camel components work nicely with the
> ComponentConfiguration API out of the box; though for components which
> don't use the @UriEndpoint annotations, you have to create an endpoint
> first before you can introspect what parameters are available. However
> for @UriEndpoint annotated endpoints you can immediately get all the
> parameter names and types (and any associated metadata such as if bean
> validation annotations are used etc).
>
> To get an idea for what tools can do with the ComponentConfiguration
> API check out the test case:
> https://github.com/apache/camel/blob/trunk/camel-core/src/test/java/org/apache/camel/impl/ComponentConfigurationTest.java#L69
>
> Note the differences between UriEndpointComponents (i.e. components
> annotated with @UriEndpoint) and with regular camel components with no
> metadata. Also note how you can start with nothing; or start with an
> existing endpoint or URI; then edit the configuration and finally
> create or edit a URI or Endpoint.
>
>
> Going forward:
> -------------------
>
> Ideally it would be good to annotate as many of the camel components
> as possible and move the documentation from the wiki into the Java
> source code as javadoc comments so we can more to a more code
> generated model of endpoint documentation; we can then generate the
> maven site for each release to make the docs a little easier to grok
> (so when folks are looking at older releases they don't see loads of
> new features all over the page that they can't use ;-). Annotating the
> existing components is pretty trivial stuff and it doesn't change the
> behaviour of the code at all; its purely for documentation generation.
>
> It would be good to get a CI job to run "mvn site:deploy" so that we
> can view & browse the generated documentation and maybe eventually
> link the wiki to the generated docs (or even include the generted docs
> inside the wiki page).
>
> I guess now we should recommend folks start writing new endpoints with
> the annotations as an easier way to start writing components; which
> are then self-documenting and more easily used in tools.
>
>
> For now I've not yet wired the EndpointConfiguration to the
> ComponentConfiguration; we could then unify the two things together so
> that EndpointConfiguration delegates to ComponentConfiguration maybe;
> then folks could create a configuration from a Component (i.e. in an
> empty command line / form in a tool) or could create a configuration
> from an Endpoint (which can then be pre-populated with the parameters
> and their types etc).
>
> What do folks think of the HTML reports? It might be nice to generate
> an index site too (e.g. a bit like JavaDoc but with endpoint schemes
> rather than packages/classes) so its easier to navigate all the camel
> endpoint configuration?
>
> Plus adding in Bean Validation annotation support would be nice (so we
> could highlight validation rules etc).
>
> Thoughts?
>
> --
> James
> -------
> Red Hat
>
> Email: jstracha@redhat.com
> Web: http://fusesource.com
> Twitter: jstrachan, fusenews
> Blog: http://macstrac.blogspot.com/
>
> Open Source Integration



-- 
James
-------
Red Hat

Email: jstracha@redhat.com
Web: http://fusesource.com
Twitter: jstrachan, fusenews
Blog: http://macstrac.blogspot.com/

Open Source Integration

Mime
View raw message