improve documentation

Author: hauner

openapi-parser/src/main/java/io/openapiparser/OpenApiResult.java

@@ -5,6 +5,7 @@
 
 package io.openapiparser;
 
+import io.openapiparser.support.Experimental;
 import io.openapiprocessor.interfaces.Writer;
 import io.openapiprocessor.jsonschema.schema.SchemaStore;
 import io.openapiprocessor.jsonschema.validator.Validator;
@@ -42,25 +43,32 @@ enum Version { V30, V31 }
     <T> T getModel (Class<T> api);
 
     /**
-     * Experimental. Bundle the document. The bundled document has to be parsed to navigate its OpenAPI model.
+     * Bundle the document, i.e. merge a multi-file document into a single file document. The bundled document has to
+     * be parsed to navigate its OpenAPI model.
      *
      * @return a raw bundled copy of the OpenAPI document.
      */
+    @Experimental
     Map<String, Object> bundle();
 
     /**
-     * Experimental. Write the document. This will produce useful results only if the document is a single file
-     * document. Bundling can be used to create a single file document.
+     * Write the document. This will produce useful results only if the document is a single file document. Bundling
+     * can be used to create a single file document.
      *
      * @param writer the target writer
      */
+    @Experimental
     void write(Writer writer) throws IOException;
 
     /**
-     * apply an OpenAPI overlay to the OpenAPI document.
+     * Apply an OpenAPI overlay to the OpenAPI document. The result document has to be parse to navigate its OpenAPI
+     * model.
+     *
      * @param overlay the overlay document
+     * @return a raw copy of the OpenAPI document with the applied overlay.
      */
-    void apply(OverlayResult overlay);
+    @Experimental
+    Map<String, Object> apply(OverlayResult overlay);
 
     /**
      * run schema validation. Retrieve the collection of validation messages from