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: jstra...@redhat.com Web: http://fusesource.com Twitter: jstrachan, fusenews Blog: http://macstrac.blogspot.com/ Open Source Integration
