docs: document ConfigScope discovery rules#7098
Open
pinin4fjords wants to merge 3 commits intonextflow-io:masterfrom
Open
docs: document ConfigScope discovery rules#7098pinin4fjords wants to merge 3 commits intonextflow-io:masterfrom
pinin4fjords wants to merge 3 commits intonextflow-io:masterfrom
Conversation
The existing example shows the top-level scope class but does not mention registering it in `build.gradle` `extensionPoints`, which is required for the v2 syntax parser to discover and validate the scope. This addition: - Documents the `extensionPoints` registration step - Adds a nested-scope example showing that fields whose type implements `ConfigScope` are auto-discovered and do not need `@ConfigOption` - Notes that `@ConfigOption` fields are not inherited (the validator uses `Class.getDeclaredFields()`) - Notes that the `types` attribute on `@ConfigOption` should only list standard Nextflow types, not runtime classes like `GString` or `Map` These rules can be inferred from the source (`SpecNode.java`, `ConfigValidator.groovy`) or learned from reviewer feedback, but were not previously documented for plugin authors. Signed-off-by: Jonathan Manning <jonathan.manning@seqera.io>
✅ Deploy Preview for nextflow-docs-staging canceled.
|
Trim the nested-scope content to better match the verbosity of neighbouring sections: - Drop the second `@ConfigOption` field from `ReportConfig`; one field is enough to demonstrate the pattern - Drop the `types=` admonition; that rule is general `@ConfigOption` guidance rather than something specific to nested scopes, and the language server already surfaces it - Tighten the inheritance note from four sentences to two Signed-off-by: Jonathan Manning <jonathan.manning@seqera.io>
Co-authored-by: Chris Hakkaart <chris.hakkaart@seqera.io> Signed-off-by: Jonathan Manning <jonathan.manning@seqera.io>
pinin4fjords
force-pushed
the
docs/configscope-discovery-rules
branch
from
69fb656 to
d6bdd49
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The plugin developer guide currently shows a single-option
ConfigScopeexample with@ScopeNameand a no-arg constructor, but does not mention registering the scope inbuild.gradleextensionPoints. Following the example as written does not eliminateUnrecognized config optionwarnings under the v2 syntax parser, because the scope is never discovered.This PR fills four related gaps:
extensionPointsregistration step required for the top-level scope to be discoveredConfigScopeare auto-discovered and do not need a@ConfigOptionannotation@ConfigOptionfields are not inherited (the validator usesClass.getDeclaredFields()), so eachConfigScopeclass must declare its options directlytypesattribute on@ConfigOptionshould only list standard Nextflow types, not runtime classes likeGString,NumberorMapThese rules are derivable from
SpecNode.javaandConfigValidator.groovy, but were not surfaced for plugin authors. Context for the gap: nextflow-io/nf-co2footprint#362 and the related upstream issue #6974.Style
The new content is additive; the existing single-option example is left intact. Triple-quoted
@Descriptionstrings,:::{note}admonitions and prose voice match the surrounding section.