[camel] branch master updated: CAMEL-15478: Add some notes on the javasource parser

[da...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

davsclaus pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/camel.git


The following commit(s) were added to refs/heads/master by this push:
     new 45d9c05  CAMEL-15478: Add some notes on the javasource parser
45d9c05 is described below

commit 45d9c05a92ad044e55b40a75dd51067b961b665a
Author: Claus Ibsen <cl...@gmail.com>
AuthorDate: Fri Sep 18 09:25:22 2020 +0200

    CAMEL-15478: Add some notes on the javasource parser
---
 .../main/java/org/apache/camel/maven/JavaSourceParser.java  | 13 ++++++++++++-
 1 file changed, 12 insertions(+), 1 deletion(-)

diff --git a/tooling/maven/camel-api-component-maven-plugin/src/main/java/org/apache/camel/maven/JavaSourceParser.java b/tooling/maven/camel-api-component-maven-plugin/src/main/java/org/apache/camel/maven/JavaSourceParser.java
index c71d494..9ac68a3 100644
--- a/tooling/maven/camel-api-component-maven-plugin/src/main/java/org/apache/camel/maven/JavaSourceParser.java
+++ b/tooling/maven/camel-api-component-maven-plugin/src/main/java/org/apache/camel/maven/JavaSourceParser.java
@@ -43,7 +43,18 @@ import org.slf4j.LoggerFactory;
 import static org.apache.camel.tooling.util.JavadocHelper.sanitizeDescription;
 
 /**
- * Parses source java to get Method Signatures from Method Summary.
+ * Java source parser that are used for parsing the proxy API class.
+ *
+ * Implementation note:
+ *
+ * This parser uses Roaster and have some workarounds to work around some limitations in Roaster.
+ * The code is specially complex in regards to resolve types from method signatures that use Java generics
+ * which can have both type variables or reference to a class (either qualified or not). The type variables
+ * can also be bounded (T extends Foo) which further complicate matters. The parser has been built with
+ * trial and errors to get it to function and work for the current set of Camel API based components.
+ *
+ * The parser was also designed to plugin and work with the old parsers that was based on javadoc harvesting.
+ * Therefore how it functions and what information it returns is adapted to be as it was with the old parser.
  */
 public class JavaSourceParser {