docs

Author: arcuri82

README.md

@@ -22,12 +22,10 @@ tr.warnings; // list of warning messages, if any
 <dependency>
     <groupId>com.webfuzzing</groupId>
     <artifactId>overlay-jvm</artifactId>
-    <version>LATEST</version>
+    <version>0.1.0</version>
 </dependency>
 ```
 
-See release info for latest version number (to replace `LATEST` placeholder).
-
 ## Dependencies
 
 This library has 2 main dependencies:

pom.xml

@@ -155,6 +155,7 @@
                    1) update release_notes.md before preparing a new release
 
                    2) manually update <version> in thi file. Typically just remove the -SNAPSHOT tag.
+                      Update the same version number in the README.md.
                       Git commit/push.
 
                    3) run:

src/main/java/com/webfuzzing/overlayjvm/Processor.java

@@ -40,6 +40,22 @@ public static Overlay parseOverlay(String overlayContent){
     }
 
 
+    /**
+     * Apply an Overlay set of transformations to an OpenAPI schema.
+     * These file representations are passed as String, representing either JSON or YAML formats.
+     * The transformed result format depends on the input OpenAPI format.
+     * For example, if OpenAPI is in YAML, and Overlay is in JSON, the transformed result is in YAML.
+     * <p>
+     * There is no validity check on the input OpenAPI schema, besides it being a syntactically valid
+     * JSON or YAML file representation.
+     * So, technically speaking, the Overlay transformation can be applied to any valid JSON/YAML file.
+     *
+     * @param openApiSchema String representation for a JSON/YAML file, in which transformations are applied on.
+     * @param overlayContent String representation for a JSON/YAML Overlay set of transformations.
+     * @return TransformationResult with the result of the transformation, including possible warning messages, if any.
+     * @throws IllegalArgumentException if the inputs are not valid JSON/YAML files, and if the Overlay is not correct
+     *         according the Overlay's specs. No validation is done on the OpenAPI specs.
+     */
     public static TransformationResult applyOverlay(String openApiSchema, String overlayContent){
 
         List<String> warnings = new ArrayList<>();

src/main/java/com/webfuzzing/overlayjvm/TransformationResult.java

@@ -5,9 +5,24 @@
 
 public class TransformationResult {
 
+    /**
+     * The original OpenAPI schema the transformation was applied on.
+     */
     public final String originalSchema;
+    /**
+     * The original Overlay applied to the input OpenAPI schema.
+     */
     public final String appliedOverlay;
+    /**
+     * The result of the transformation, i.e., when appliedOverlay is applied to the originalSchema.
+     */
     public final String transformedSchema;
+    /**
+     * Possible warning messages when applying the transformations.
+     * For example, actions with RFC 9535 json paths that result in no node selection are marked as warning,
+     * although technically they are non-erroneous (according to the Overlay specs).
+     * This can be useful when debugging json paths, instead of silently ignoring actions that led to no modifications.
+     */
     public final List<String> warnings;
 
     public TransformationResult(String originalSchema, String appliedOverlay, String transformedSchema, List<String> warnings) {