updated comments

Author: raydac

jcp/src/main/java/com/igormaznitsa/jcp/context/CommentTextProcessor.java

@@ -4,26 +4,28 @@
 import com.igormaznitsa.jcp.exceptions.FilePositionInfo;
 
 /**
- * Custom processor to detect and process uncommenting text line or text block
- * defined through //$ and //$$ directives. It can return the same value or
- * changed one. The processor is called after ext prepared for injection into preprocessed source.
- * If activated merge block mode for preprocessor so sequentially
- * situated lines started with """ will be merged into single text block (and """ will be removed)
+ * A custom processor for detecting and handling uncommenting directives in source text.
+ * This processor recognizes lines or blocks marked with `//$` and `//$$` and can either
+ * return them unchanged or modify them as needed. It is invoked after the external text
+ * is prepared for injection into the preprocessed source.
+ * If block merging is enabled, consecutive lines beginning with `"""` will be merged
+ * into a single text block, and the `"""` markers will be removed.
  *
  * @since 7.2.0
  */
 public interface CommentTextProcessor extends PreprocessorContextListener {
 
   /**
-   * Process uncommented text detected in //$ or //$$ sections. If processing not needed then the provided text must be returned.
+   * Processes uncommented text detected in `//$` or `//$$` sections.
+   * If no transformation is needed, the original text must be returned unchanged.
    *
-   * @param recommendedIndent indent to be recommended for the processed text if it will be processed
-   * @param uncommentedText   the text which was uncommented and needs processing, must not be null
-   * @param fileContainer     the source file info container calling the processor, must not be null
-   * @param positionInfo      position of the uncommented line or the first line of the uncommented text block, must not be null
-   * @param context           the current preprocessor context, must not be null
-   * @param state             the current preprocess state, must not be null
-   * @return must return value as the same text or as the changed one.
+   * @param recommendedIndent the suggested indentation level for the processed text, if any modifications are applied
+   * @param uncommentedText   the text that was uncommented and is subject to processing; must not be null
+   * @param fileContainer     the container holding metadata about the source file invoking the processor; must not be null
+   * @param positionInfo      the position of the uncommented line or the first line of the uncommented block; must not be null
+   * @param context           the current preprocessor context; must not be null
+   * @param state             the current preprocessor state; must not be null
+   * @return the processed text, which may be unchanged or modified
    * @since 7.2.1
    */
   String processUncommentedText(
@@ -35,10 +37,16 @@ String processUncommentedText(
       PreprocessingState state);
 
   /**
-   * Returns flag that the preprocessor is allowed and can be called. It gets full info about current context and file so can make decision on fly.
-   * It will be called before every processor call.
+   * Indicates whether the preprocessor is allowed to run in the current context.
+   * This method is invoked before each call to the processor and receives complete
+   * information about the current context and source file, enabling it to make a
+   * dynamic decision.
    *
-   * @return true if the preprocessor allowed, false if not
+   * @param fileContainer     the container holding metadata about the source file invoking the processor; must not be null
+   * @param positionInfo      the position of the uncommented line or the first line of the uncommented block; must not be null
+   * @param context           the current preprocessor context; must not be null
+   * @param state             the current preprocessor state; must not be null
+   * @return {@code true} if the preprocessor is permitted to run; {@code false} otherwise
    * @since 7.2.1
    */
   boolean isAllowed(