Excludes hidden options, params, and subcommands from man page generation #1064

bdemers · 2020-05-21T18:16:08Z

bdemers · 2020-05-21T18:18:42Z

src/main/java/picocli/CommandLine.java

@@ -6693,6 +6705,7 @@ void initDefaultValueProvider(Class<? extends IDefaultValueProvider> value, IFac
            void updateHelpCommand(boolean value)           { if (isNonDefault(value, DEFAULT_IS_HELP_COMMAND))             {isHelpCommand = value;} }
            void updateSubcommandsRepeatable(boolean value) { if (isNonDefault(value, DEFAULT_SUBCOMMANDS_REPEATABLE))      {subcommandsRepeatable = value;} }
            void updateAddMethodSubcommands(boolean value)  { if (isNonDefault(value, DEFAULT_IS_ADD_METHOD_SUBCOMMANDS))   {isAddMethodSubcommands = value;} }
+            void updateHidden(boolean value)                { if (isNonDefault(value, DEFAULT_HIDDEN)) { isHidden = value; } }


@remkop I didn't see another way of access the hidden prop, but I'm probably missing something as it is used for the help text output.
If you have any alternative idea let me know, and I could remove this method (and revert the MINOR version bump)

@bdemers The @Command(hidden) value is captured as a property of the command's UsageHelpMessageSpec. I admit this is not easy to find. Perhaps the javadoc for picocli.CommandLine.Command#hidden should have a @see picocli.CommandLine.Model.UsageMessageSpec#hidden() reference to make this a bit easier to find. Can you do that as part of the PR?

The Help class has its own map of subcommands, and when this map is built up in CommandLine.Help#addAllSubcommands, hidden subcommands are excluded. This means that the logic for Help is simpler, because it does not need to care about hidden subcommands any more, but can be a bit puzzling if you miss this. This should be mentioned in the javadoc for Help#addAllSubcommands and the javadoc for Help#subcommands. Can you include that in the PR?

Good finds, thanks! 👍

Since we can use picocli.CommandLine.Model.UsageMessageSpec#hidden, all changes to CommandLine can be reverted.

codecov-commenter · 2020-05-21T18:24:44Z

Codecov Report

Merging #1064 into master will increase coverage by 0.10%.
The diff coverage is n/a.

@@             Coverage Diff              @@
##             master    #1064      +/-   ##
============================================
+ Coverage     94.35%   94.46%   +0.10%     
- Complexity      442      448       +6     
============================================
  Files             2        2              
  Lines          6484     6571      +87     
  Branches       1736     1765      +29     
============================================
+ Hits           6118     6207      +89     
+ Misses           94       93       -1     
+ Partials        272      271       -1

Impacted Files	Coverage Δ	Complexity Δ
src/main/java/picocli/AutoComplete.java	`96.98% <0.00%> (-0.06%)`	`139.00% <0.00%> (ø%)`
src/main/java/picocli/CommandLine.java	`94.31% <0.00%> (+0.12%)`	`309.00% <0.00%> (+6.00%)`

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update d1b9a30...2c96e69. Read the comment docs.

remkop

Overall good progress! Thanks for taking care of this!
I added some more comments.

remkop · 2020-05-21T21:35:05Z

gradle.properties

@@ -16,7 +16,7 @@ springBootVersion   = 2.2.2.RELEASE
 projectPreviousReleaseVersion = 4\\.3\\.2
 # projectPreviousVersionRegex may be a SNAPSHOT
 projectPreviousVersionRegex   = 4\\.3\\.2
-projectVersion                = 4.3.3-SNAPSHOT
+projectVersion                = 4.4.0-SNAPSHOT


I think this can be reverted.

remkop · 2020-05-21T21:35:54Z

picocli-codegen/src/main/java/picocli/codegen/docgen/manpage/ManPageGenerator.java

@@ -193,7 +193,7 @@ static int generateManPage(Config config, CommandSpec... specs) throws IOExcepti
            // recursively create man pages for subcommands
            for (CommandLine sub : spec.subcommands().values()) {
                CommandSpec subSpec = sub.getCommandSpec();
-                if (done.contains(subSpec)) {continue;}
+                if (done.contains(subSpec) || subSpec.hidden()) {continue;}


We can use picocli.CommandLine.Model.UsageMessageSpec#hidden here.

remkop · 2020-05-21T22:26:14Z

picocli-codegen/src/main/java/picocli/codegen/docgen/manpage/ManPageGenerator.java

-        pw.printf("  %s%n", rows[0][4]);
-        for (int i = 1; i < rows.length; i++) {
-            pw.printf("+%n%s%n", rows[i][4]);
+        if (!positional.hidden()) {


Should we have a similar if statement in writeOption : if (!option.hidden()) ...,
or should we exclude hidden PositionalParamSpec before the writePositional method is called?
I would like it if we can do this in a consistent manner for options, positionals and commands.

+1, keeping the check in writeOption/writePositional is easier, as writePositional is called from multiple places.

However, the check for the subcommands gets a little trickier, the subcommands need to be removed before processing to avoid the tag/"Commands" heading.

Thoughts?

After thinking about this some more, I think your original approach to filter out hidden args first is better.

The reason is the same as for subcommands: if all options or positional parameters are hidden, we don't want to include the tag and heading in the output. (see also #1071)

remkop · 2020-05-21T22:27:47Z

src/main/java/picocli/CommandLine.java

@@ -6693,6 +6705,7 @@ void initDefaultValueProvider(Class<? extends IDefaultValueProvider> value, IFac
            void updateHelpCommand(boolean value)           { if (isNonDefault(value, DEFAULT_IS_HELP_COMMAND))             {isHelpCommand = value;} }
            void updateSubcommandsRepeatable(boolean value) { if (isNonDefault(value, DEFAULT_SUBCOMMANDS_REPEATABLE))      {subcommandsRepeatable = value;} }
            void updateAddMethodSubcommands(boolean value)  { if (isNonDefault(value, DEFAULT_IS_ADD_METHOD_SUBCOMMANDS))   {isAddMethodSubcommands = value;} }
+            void updateHidden(boolean value)                { if (isNonDefault(value, DEFAULT_HIDDEN)) { isHidden = value; } }


Since we can use picocli.CommandLine.Model.UsageMessageSpec#hidden, all changes to CommandLine can be reverted.

remkop · 2020-05-26T00:24:26Z

FYI: This issue may be relevant: #1071

…tion Fixes: remkop#1063

bdemers · 2020-05-26T15:47:11Z

Still one more comment to address, but I reverted the new method and version bump

remkop · 2020-05-26T22:14:42Z

Thanks for the updates! Please let me know when this is ready for review.

bdemers · 2020-05-27T02:11:44Z

Hey @remkop it's ready. though I did have a question/comment: https://github.com/remkop/picocli/pull/1064/files#r430546512

remkop

I replied to your comment, but #1071 made clear that your original approach is better:
Filter out hidden args first allows us to avoid emitting a header without any content in the man page.

…are all hiddend

bdemers · 2020-05-27T14:35:37Z

@remkop good call, I updated the test to make sure the Arguments header is not included when all of the args are hidden

remkop

I think we are very close now.
For positional parameters, the man page now correctly does not show an == Arguments header if all positionals are either hidden, or part of a group (so it will be shown under the group header).

We should do the same for the == Options header.

remkop · 2020-05-27T22:41:54Z

picocli-codegen/src/main/java/picocli/codegen/docgen/manpage/ManPageGenerator.java

+            if (iter.next().hidden()) {
+                iter.remove();
+            }
+        }


I believe this is the right approach, but we should do this at the top of this method, before rendering the == Options header.

Ahh, I missed that one, i just pushed an update

remkop · 2020-05-28T00:12:58Z

It may be good to have a test for the case where all options are hidden.

remkop · 2020-05-28T11:32:09Z

I went ahead and merged this into master.
Thank you for the contribution!

bdemers commented May 21, 2020

View reviewed changes

remkop requested changes May 21, 2020

View reviewed changes

remkop added this to the 4.4 milestone May 21, 2020

remkop added the theme: codegen An issue or change related to the picocli-codegen module label May 21, 2020

Excludes hidden options, params, and subcommands from man page genera…

2f6de1c

…tion Fixes: remkop#1063

bdemers force-pushed the hidden-man-options branch from 90060d0 to 2f6de1c Compare May 26, 2020 15:46

Move option.hidden logic to writeOption method

245ef7f

bdemers force-pushed the hidden-man-options branch from dc93d5e to 245ef7f Compare May 26, 2020 16:21

remkop requested changes May 27, 2020

View reviewed changes

bdemers added 2 commits May 27, 2020 09:55

revert previous changes

ae44103

Updated ManPageGenerator logic to NOT print arguments header if they …

a3ad56e

…are all hiddend

Fix old java diamond compile error

172c313

remkop requested changes May 27, 2020

View reviewed changes

Moving option filtering logic above header tag in ManPageGen

2c96e69

remkop merged commit 4e14674 into remkop:master May 28, 2020

remkop added a commit that referenced this pull request May 28, 2020

[#1063][#1064] minor improvements; added test; update RELEASE-NOTES.md

9cc6b1a

remkop mentioned this pull request May 28, 2020

Show end-of-options -- in manual page #1077

Closed

bdemers deleted the hidden-man-options branch May 28, 2020 14:03

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Excludes hidden options, params, and subcommands from man page generation #1064

Excludes hidden options, params, and subcommands from man page generation #1064

bdemers commented May 21, 2020 •

edited

Loading

bdemers May 21, 2020

remkop May 21, 2020

remkop May 21, 2020

codecov-commenter commented May 21, 2020 •

edited

Loading

remkop left a comment

remkop May 21, 2020

remkop May 21, 2020

remkop May 21, 2020

bdemers May 26, 2020

remkop May 27, 2020

remkop May 21, 2020

remkop commented May 26, 2020

bdemers commented May 26, 2020

remkop commented May 26, 2020 •

edited

Loading

bdemers commented May 27, 2020

remkop left a comment

bdemers commented May 27, 2020

remkop left a comment

remkop May 27, 2020

bdemers May 28, 2020

remkop commented May 28, 2020

remkop commented May 28, 2020

Excludes hidden options, params, and subcommands from man page generation #1064

Excludes hidden options, params, and subcommands from man page generation #1064

Conversation

bdemers commented May 21, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

codecov-commenter commented May 21, 2020 • edited Loading

Codecov Report

remkop left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

remkop commented May 26, 2020

bdemers commented May 26, 2020

remkop commented May 26, 2020 • edited Loading

bdemers commented May 27, 2020

remkop left a comment

Choose a reason for hiding this comment

bdemers commented May 27, 2020

remkop left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

remkop commented May 28, 2020

remkop commented May 28, 2020

bdemers commented May 21, 2020 •

edited

Loading

codecov-commenter commented May 21, 2020 •

edited

Loading

remkop commented May 26, 2020 •

edited

Loading