Refactor Constant, Function, DslType -> Description

Signed-off-by: Ben Sherman <[email protected]>

src/main/groovy/nextflow/config/dsl/ConfigSchema.java

@@ -20,7 +20,7 @@
 import java.util.Map;
 
 import nextflow.config.scopes.*;
-import nextflow.script.dsl.Function;
+import nextflow.script.dsl.Description;
 import nextflow.script.dsl.ProcessDirectiveDsl;
 
 public class ConfigSchema {
@@ -110,7 +110,7 @@ private static Map<String, String> getConfigOptions() {
         }
         // derive process config from process directives
         for( var method : ProcessDirectiveDsl.class.getDeclaredMethods() ) {
-            var annot = method.getAnnotation(Function.class);
+            var annot = method.getAnnotation(Description.class);
             if( annot == null )
                 continue;
             var name = "process." + method.getName();

src/main/groovy/nextflow/lsp/ast/ASTNodeStringUtils.java

@@ -21,10 +21,8 @@
 import groovy.lang.groovydoc.Groovydoc;
 import nextflow.lsp.services.util.FormattingOptions;
 import nextflow.lsp.services.util.Formatter;
-import nextflow.script.dsl.Constant;
-import nextflow.script.dsl.DslType;
+import nextflow.script.dsl.Description;
 import nextflow.script.dsl.FeatureFlag;
-import nextflow.script.dsl.Function;
 import nextflow.script.dsl.Operator;
 import nextflow.script.dsl.OutputDsl;
 import nextflow.script.dsl.ProcessDirectiveDsl;
@@ -246,7 +244,7 @@ private static String variableToLabel(Variable variable) {
     public static String getDocumentation(ASTNode node) {
         if( node instanceof FeatureFlagNode ffn ) {
             if( ffn.target instanceof AnnotatedNode an )
-                return annotationValueToMarkdown(an, FeatureFlag.class, "description");
+                return annotationValueToMarkdown(an);
         }
 
         if( node instanceof WorkflowNode wn )
@@ -261,40 +259,36 @@ public static String getDocumentation(ASTNode node) {
         if( node instanceof ClassNode cn ) {
             var result = groovydocToMarkdown(cn.getGroovydoc());
             if( result == null )
-                result = annotationValueToMarkdown(cn, DslType.class);
+                result = annotationValueToMarkdown(cn);
             return result;
         }
 
         if( node instanceof FieldNode fn ) {
             var result = groovydocToMarkdown(fn.getGroovydoc());
             if( result == null )
-                result = annotationValueToMarkdown(fn, Constant.class);
+                result = annotationValueToMarkdown(fn);
             return result;
         }
 
         if( node instanceof MethodNode mn ) {
             var result = groovydocToMarkdown(mn.getGroovydoc());
             if( result == null )
-                result = annotationValueToMarkdown(mn, Function.class);
+                result = annotationValueToMarkdown(mn);
             return result;
         }
 
         return null;
     }
 
-    private static String annotationValueToMarkdown(AnnotatedNode node, Class type, String member) {
-        return findAnnotation(node, type)
+    private static String annotationValueToMarkdown(AnnotatedNode node) {
+        return findAnnotation(node, Description.class)
             .map((an) -> {
-                var description = an.getMember(member).getText();
+                var description = an.getMember("value").getText();
                 return StringGroovyMethods.stripIndent(description, true).trim();
             })
             .orElse(null);
     }
 
-    private static String annotationValueToMarkdown(AnnotatedNode node, Class type) {
-        return annotationValueToMarkdown(node, type, "value");
-    }
-
     private static String groovydocToMarkdown(Groovydoc groovydoc) {
         if( groovydoc == null || !groovydoc.isPresent() )
             return null;

src/main/groovy/nextflow/lsp/services/script/ScriptCompletionProvider.java

@@ -30,10 +30,10 @@
 import nextflow.lsp.services.CompletionProvider;
 import nextflow.lsp.util.LanguageServerUtils;
 import nextflow.lsp.util.Logger;
-import nextflow.script.dsl.Constant;
+import nextflow.script.dsl.Description;
 import nextflow.script.dsl.FeatureFlag;
 import nextflow.script.dsl.FeatureFlagDsl;
-import nextflow.script.dsl.Function;
+import nextflow.script.dsl.Description;
 import nextflow.script.dsl.ScriptDsl;
 import nextflow.script.v2.FunctionNode;
 import nextflow.script.v2.InvalidDeclaration;
@@ -288,12 +288,12 @@ private void populateLocalVariables(VariableScope scope, String namePrefix, Set<
     private void populateItemsFromDslScope(ClassNode cn, String namePrefix, Set<String> existingNames, List<CompletionItem> items) {
         while( cn != null && !ClassHelper.isObjectType(cn) ) {
             var constants = cn.getFields().stream()
-                .filter(fn -> findAnnotation(fn, Constant.class).isPresent())
+                .filter(fn -> findAnnotation(fn, Description.class).isPresent())
                 .iterator();
             populateItemsFromFields(constants, namePrefix, existingNames, items);
 
             var functions = cn.getMethods().stream()
-                .filter(mn -> findAnnotation(mn, Function.class).isPresent())
+                .filter(mn -> findAnnotation(mn, Description.class).isPresent())
                 .iterator();
             populateItemsFromMethods(functions, namePrefix, existingNames, items);
 
@@ -607,13 +607,14 @@ def greet(greeting, name) {
         ));
 
         for( var field : FeatureFlagDsl.class.getDeclaredFields() ) {
-            var annot = field.getAnnotation(FeatureFlag.class);
-            if( annot == null )
+            var name = field.getAnnotation(FeatureFlag.class);
+            var description = field.getAnnotation(Description.class);
+            if( name == null || description == null )
                 continue;
             snippets.add(new Snippet(
-                annot.name(),
-                annot.description(),
-                annot.name() + " = "
+                name.value(),
+                description.value(),
+                name.value() + " = "
             ));
         }
 

src/main/groovy/nextflow/lsp/services/script/VariableScopeVisitor.java

@@ -34,11 +34,10 @@
 import nextflow.lsp.compiler.PhaseAware;
 import nextflow.lsp.compiler.Phases;
 import nextflow.lsp.compiler.RelatedInformationAware;
-import nextflow.script.dsl.Constant;
+import nextflow.script.dsl.Description;
 import nextflow.script.dsl.EntryWorkflowDsl;
 import nextflow.script.dsl.FeatureFlag;
 import nextflow.script.dsl.FeatureFlagDsl;
-import nextflow.script.dsl.Function;
 import nextflow.script.dsl.OutputDsl;
 import nextflow.script.dsl.ParamsMap;
 import nextflow.script.dsl.ProcessDsl;
@@ -193,7 +192,7 @@ public void visitFeatureFlag(FeatureFlagNode node) {
         var result = cn.getFields().stream()
             .filter(fn ->
                 findAnnotation(fn, FeatureFlag.class)
-                    .map(an -> an.getMember("name").getText())
+                    .map(an -> an.getMember("value").getText())
                     .map(name -> name.equals(node.name))
                     .orElse(false)
             )
@@ -284,7 +283,7 @@ private void declareParameters() {
             fn.setHasNoRealSourcePosition(true);
             fn.setDeclaringClass(cn);
             fn.setSynthetic(true);
-            var an = new AnnotationNode(ClassHelper.makeCached(Constant.class));
+            var an = new AnnotationNode(ClassHelper.makeCached(Description.class));
             an.addMember("value", new ConstantExpression(description));
             fn.addAnnotation(an);
             cn.addField(fn);
@@ -626,7 +625,7 @@ else if( node instanceof VariableExpression ve ) {
     private void declareAssignedVariable(VariableExpression ve) {
         var variable = findVariableDeclaration(ve.getName(), ve);
         if( variable != null ) {
-            if( variable instanceof FieldNode fn && findAnnotation(fn, Constant.class).isPresent() )
+            if( variable instanceof FieldNode fn && findAnnotation(fn, Description.class).isPresent() )
                 addError("Built-in variable cannot be re-assigned", ve);
             else
                 checkExternalWriteInClosure(ve, variable);
@@ -666,7 +665,7 @@ else if( node instanceof BinaryExpression be && be.getOperation().getType() == T
         if( target == null )
             return;
         var variable = findVariableDeclaration(target.getName(), target);
-        if( variable instanceof FieldNode fn && findAnnotation(fn, Constant.class).isPresent() ) {
+        if( variable instanceof FieldNode fn && findAnnotation(fn, Description.class).isPresent() ) {
             if( "params".equals(variable.getName()) )
                 sourceUnit.addWarning("Params should be declared at the top-level (i.e. outside the workflow)", target);
             // TODO: re-enable after workflow.onComplete bug is fixed
@@ -877,7 +876,7 @@ private Variable findVariableDeclaration(String name, ASTNode node) {
     private Variable findClassMember(ClassNode cn, String name, ASTNode node) {
         while( cn != null && !ClassHelper.isObjectType(cn) ) {
             var fn = cn.getDeclaredField(name);
-            if( fn != null && findAnnotation(fn, Constant.class).isPresent() ) {
+            if( fn != null && findAnnotation(fn, Description.class).isPresent() ) {
                 if( findAnnotation(fn, Deprecated.class).isPresent() )
                     addFutureWarning("`" + name + "` is deprecated and will be removed in a future version", node);
                 return fn;
@@ -889,7 +888,7 @@ private Variable findClassMember(ClassNode cn, String name, ASTNode node) {
                 if( mn instanceof FunctionNode || mn instanceof ProcessNode || mn instanceof WorkflowNode ) {
                     return wrapMethodAsVariable(mn, cn);
                 }
-                if( findAnnotation(mn, Function.class).isPresent() ) {
+                if( findAnnotation(mn, Description.class).isPresent() ) {
                     if( findAnnotation(mn, Deprecated.class).isPresent() )
                         addFutureWarning("`" + name + "` is deprecated and will be removed in a future version", node);
                     return wrapMethodAsVariable(mn, cn);

src/main/groovy/nextflow/script/dsl/Constant.java → src/main/groovy/nextflow/script/dsl/Description.java

@@ -21,7 +21,7 @@
 import java.lang.annotation.Target;
 
 @Retention(RetentionPolicy.RUNTIME)
-@Target(ElementType.FIELD)
-public @interface Constant {
+@Target({ ElementType.TYPE, ElementType.FIELD, ElementType.METHOD })
+public @interface Description {
     String value();
 }

src/main/groovy/nextflow/script/dsl/FeatureFlag.java

@@ -23,6 +23,5 @@
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.FIELD)
 public @interface FeatureFlag {
-    String name();
-    String description();
+    String value();
 }

src/main/groovy/nextflow/script/dsl/FeatureFlagDsl.java

@@ -18,54 +18,47 @@
 public class FeatureFlagDsl {
 
     @Deprecated
-    @FeatureFlag(
-        name="nextflow.enable.configProcessNamesValidation",
-        description="""
-            When `true`, prints a warning for every `withName:` process selector that doesn't match a process in the pipeline (default: `true`).
-        """)
+    @FeatureFlag("nextflow.enable.configProcessNamesValidation")
+    @Description("""
+        When `true`, prints a warning for every `withName:` process selector that doesn't match a process in the pipeline (default: `true`).
+    """)
     public boolean configProcessNamesValidation;
 
     @Deprecated
-    @FeatureFlag(
-        name="nextflow.enable.dsl",
-        description="""
-            Defines the DSL version (`1` or `2`).
-        """)
+    @FeatureFlag("nextflow.enable.dsl")
+    @Description("""
+        Defines the DSL version (`1` or `2`).
+    """)
     public float dsl;
 
-    @FeatureFlag(
-        name="nextflow.enable.moduleBinaries",
-        description="""
-            When `true`, enables the use of modules with executable scripts i.e. [module binaries](https://nextflow.io/docs/latest/module.html#module-binaries).
-        """)
+    @FeatureFlag("nextflow.enable.moduleBinaries")
+    @Description("""
+        When `true`, enables the use of modules with executable scripts i.e. [module binaries](https://nextflow.io/docs/latest/module.html#module-binaries).
+    """)
     public boolean moduleBinaries;
 
-    @FeatureFlag(
-        name="nextflow.enable.strict",
-        description="""
-            When `true`, the pipeline is executed in [strict mode](https://nextflow.io/docs/latest/reference/feature-flags.html).
-        """)
+    @FeatureFlag("nextflow.enable.strict")
+    @Description("""
+        When `true`, the pipeline is executed in [strict mode](https://nextflow.io/docs/latest/reference/feature-flags.html).
+    """)
     public boolean strict;
 
-    @FeatureFlag(
-        name="nextflow.preview.output",
-        description="""
-            When `true`, enables the use of the [workflow output definition](https://nextflow.io/docs/latest/workflow.html#workflow-output-def).
-        """)
+    @FeatureFlag("nextflow.preview.output")
+    @Description("""
+        When `true`, enables the use of the [workflow output definition](https://nextflow.io/docs/latest/workflow.html#workflow-output-def).
+    """)
     public boolean previewOutput;
 
-    @FeatureFlag(
-        name="nextflow.preview.recursion",
-        description="""
-            When `true`, enables the use of [process and workflow recursion](https://github.com/nextflow-io/nextflow/discussions/2521).
-        """)
+    @FeatureFlag("nextflow.preview.recursion")
+    @Description("""
+        When `true`, enables the use of [process and workflow recursion](https://github.com/nextflow-io/nextflow/discussions/2521).
+    """)
     public boolean previewRecursion;
 
-    @FeatureFlag(
-        name="nextflow.preview.topic",
-        description="""
-            When `true`, enables the use of [topic channels](https://nextflow.io/docs/latest/reference/channel.html#topic).
-        """)
+    @FeatureFlag("nextflow.preview.topic")
+    @Description("""
+        When `true`, enables the use of [topic channels](https://nextflow.io/docs/latest/reference/channel.html#topic).
+    """)
     public boolean previewTopic;
 
 }