camel-issues mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "ASF GitHub Bot (JIRA)" <j...@apache.org>
Subject [jira] [Commented] (CAMEL-8197) Create Maven plugin to inject EIP documentation into the spring and blueprint XML DSL
Date Mon, 09 Feb 2015 07:45:35 GMT

    [ https://issues.apache.org/jira/browse/CAMEL-8197?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=14311900#comment-14311900
] 

ASF GitHub Bot commented on CAMEL-8197:
---------------------------------------

GitHub user nkukhar opened a pull request:

    https://github.com/apache/camel/pull/387

    [CAMEL-8197] Create Maven plugin to inject EIP documentation into the spring and blueprint
XML DSL.

    This is the firs version of documentation enricher plugin. Currently it works preaty well
and injects documentation to majority of XSD schema, but it still has room for improvements:
    1) It doesn't enrich documentation to base types. (i.e. if <xs:complexType> has
some extension <xs:extension base="tns:dataFormat"> then documentation for <>
<xs:complexType name='dataFormat'> wont be added).
    2) It has no unit tests.

You can merge this pull request into a Git repository by running:

    $ git pull https://github.com/nkukhar/camel CAMEL-8197

Alternatively you can review and apply these changes as the patch at:

    https://github.com/apache/camel/pull/387.patch

To close this pull request, make a commit to your master/trunk branch
with (at least) the following in the commit message:

    This closes #387
    
----
commit 8a11d3dbfe59068e65751de7fee0c0b1eac88d5f
Author: nkukhar <kukhar.n@gmail.com>
Date:   2015-02-09T07:19:06Z

    CAMEL-8197 Added maven plagin to inject EIP documentation into the spring and blueprint
XML DSL.

commit 9632d88b5a1f9706febd31d3127604a43e55c1f0
Author: nkukhar <kukhar.n@gmail.com>
Date:   2015-02-09T07:20:51Z

    Minor refactoring

commit b5eb8c8caf94ce07120f82a53c54736ea0cd959b
Author: nkukhar <kukhar.n@gmail.com>
Date:   2015-02-09T07:21:45Z

    added missing files

----


> Create Maven plugin to inject EIP documentation into the spring and blueprint XML DSL
> -------------------------------------------------------------------------------------
>
>                 Key: CAMEL-8197
>                 URL: https://issues.apache.org/jira/browse/CAMEL-8197
>             Project: Camel
>          Issue Type: Sub-task
>          Components: eip, tooling
>            Reporter: Claus Ibsen
>            Assignee: Willem Jiang
>             Fix For: 2.15.0
>
>
> So we can include documentation out of the box in the XSD schema files, which allows
end users to better work with Camel, as their IDE editors can show the documentation in the
IDE.
> To do this we need to
> 1)
> Create a new Maven plugin at
> https://github.com/apache/camel/tree/master/tooling/maven
> which can be inspired by
> https://github.com/apache/camel/tree/master/tooling/maven/camel-package-maven-plugin
> 2)
> Run this plugin in camel-spring and camel-blueprint, so it can read the camel-spring.xsd,
camel-blueprint.xsd file, and inject documentation.
> 3)
> Parse the XSD maybe using SAX, and inject the documentation.
> For each xs:element in the top of the schema file
> http://camel.apache.org/schema/spring/camel-spring.xsd
> Then use the name, eg (name=split)
> {code}
> <xs:element name="split" type="tns:splitDefinition"/>
> {code}
> To find the split.json file in camel-core. Then the json file has the documentation for
that type (including inherited types).
> So for the split definition
> {code}
> <xs:complexType name="splitDefinition">
> <xs:complexContent>
> <xs:extension base="tns:expressionNode">
> <xs:sequence/>
> <xs:attribute name="parallelProcessing" type="xs:boolean"/>
> <xs:attribute name="strategyRef" type="xs:string"/>
> <xs:attribute name="strategyMethodName" type="xs:string"/>
> <xs:attribute name="strategyMethodAllowNull" type="xs:boolean"/>
> <xs:attribute name="executorServiceRef" type="xs:string"/>
> <xs:attribute name="streaming" type="xs:boolean"/>
> <xs:attribute name="stopOnException" type="xs:boolean"/>
> <xs:attribute name="timeout" type="xs:long"/>
> <xs:attribute name="onPrepareRef" type="xs:string"/>
> <xs:attribute name="shareUnitOfWork" type="xs:boolean"/>
> <xs:anyAttribute namespace="##other" processContents="skip"/>
> </xs:extension>
> </xs:complexContent>
> </xs:complexType>
> {code}
> We can find the description of these attributes, and elements from the json file.
> For example for the streaming attribute we have
> {code}
>  "streaming": { "kind": "attribute": "required": "false", "type": "boolean", "javaType":
"java.lang.Boolean", "description": "The splitter should use streaming -- exchanges are being
sent as the data for them becomes available. This improves throughput and memory usage but
it has a drawback: - the sent exchanges will no longer contain the link org.apache.camel.ExchangeSPLIT_SIZE
header property"
> {code}
> Then add the needed xs:annotation to document it. 
> http://www.w3schools.com/schema/el_annotation.asp
> Which should be
> {code}
> <xs:annotation>
>   <xs:documentation xml:lang="en">
> The splitter should use streaming -- exchanges are being sent as the data for them becomes
available. This improves throughput and memory usage but it has a drawback: - the sent exchanges
will no longer contain the link org.apache.camel.ExchangeSPLIT_SIZE header property  
>   </xs:documentation>
> </xs:annotation>
> {code}
> Notice that the xsd will become bigger due the verbosity of how to annotate xsd fields.

> Mind that sometimes there is not yet documentation, so check for not empty value.
> To parse the json file, then use this class from camel-core
> {code}
> List<Map<String, String>> rows = JsonSchemaHelper.parseJsonSchema("properties",
json, true);
> {code}
> Then you have a map with key/value for all those values.



--
This message was sent by Atlassian JIRA
(v6.3.4#6332)

Mime
View raw message