Return-Path: 
 <issues-return-21932-apmail-camel-issues-archive=camel.apache.org@camel.apache.org>
X-Original-To: apmail-camel-issues-archive@minotaur.apache.org
Delivered-To: apmail-camel-issues-archive@minotaur.apache.org
Received: from mail.apache.org (hermes.apache.org [140.211.11.3])
	by minotaur.apache.org (Postfix) with SMTP id 60A141096A
	for <apmail-camel-issues-archive@minotaur.apache.org>;
 Tue, 10 Feb 2015 12:35:18 +0000 (UTC)
Received: (qmail 52249 invoked by uid 500); 10 Feb 2015 12:35:11 -0000
Delivered-To: apmail-camel-issues-archive@camel.apache.org
Received: (qmail 52213 invoked by uid 500); 10 Feb 2015 12:35:11 -0000
Mailing-List: contact issues-help@camel.apache.org; run by ezmlm
Precedence: bulk
List-Help: <mailto:issues-help@camel.apache.org>
List-Unsubscribe: <mailto:issues-unsubscribe@camel.apache.org>
List-Post: <mailto:issues@camel.apache.org>
List-Id: <issues.camel.apache.org>
Reply-To: dev@camel.apache.org
Delivered-To: mailing list issues@camel.apache.org
Received: (qmail 52204 invoked by uid 99); 10 Feb 2015 12:35:11 -0000
Received: from arcas.apache.org (HELO arcas.apache.org) (140.211.11.28)
    by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 10 Feb 2015 12:35:11 +0000
Date: Tue, 10 Feb 2015 12:35:11 +0000 (UTC)
From: "Claus Ibsen (JIRA)" <jira@apache.org>
To: issues@camel.apache.org
Message-ID: <JIRA.12764173.1419934784000.56.1423571711743@Atlassian.JIRA>
In-Reply-To: <JIRA.12764173.1419934784000@Atlassian.JIRA>
References: <JIRA.12764173.1419934784000@Atlassian.JIRA>
 <JIRA.12764173.1419934784017@arcas>
Subject: [jira] [Comment Edited] (CAMEL-8197) Create Maven plugin to inject
 EIP documentation into the spring and blueprint XML DSL
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: 7bit
X-JIRA-FingerPrint: 30527f35849b9dde25b450d4833f0394


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

Claus Ibsen edited comment on CAMEL-8197 at 2/10/15 12:34 PM:
--------------------------------------------------------------

There are two things left to do

- include doc for abstract/base types (such as SendDefinition) which are used by <to>
- the schema file in the JAR is the old schema, we should include the schema with the documentation *DONE*


was (Author: davsclaus):
There are two things left to do

- include doc for abstract/base types (such as SendDefinition) which are used by <to>
- the schema file in the JAR is the old schema, we should include the schema with the documentation

> 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)