Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Print out CLI help message when inspecting commands #2522

Merged
merged 6 commits into from
May 16, 2023

Conversation

lihaoyi
Copy link
Member

@lihaoyi lihaoyi commented May 16, 2023

Fixes #2198

There's a bit of duplication if a user both adds @mainargs.arg(doc = "...") scala annotation as well as a @param foo scaladoc annotation, but that's an inherent issue with mainargs and not something we aim to fix here.

We render the mainargs CLI help message the same way it's done in mainargs. There isn't a nice helper that renders the whole thing at once, so i have to piece it together from various helpers, but it's not too complex and works out ok.

Tested via additions to integration.feature[docannotations].local.test, and manually

$ ./mill -i dev.run example/basic/1-simple-scala -i inspect run # command with 1 arg
run(JavaModule.scala:720)
    Runs this modules code in a subprocess and waits for it to finish

    args <str>...

Inputs:
    finalMainClass
    runClasspath
    forkArgs
    forkEnv
    forkWorkingDir
    runUseArgsFile

$ ./mill -i dev.run example/basic/1-simple-scala -i inspect compile # not a command
compile(ScalaModule.scala:211)
    Compiles the current module to generate compiled classfiles/bytecode.

    When you override this, you probably also want to override [[bspCompileClassesPath]].

Inputs:
    scalaVersion
    upstreamCompileOutput
    allSourceFiles
    compileClasspath
    javacOptions
    scalaOrganization
    allScalacOptions
    scalaCompilerClasspath
    scalacPluginClasspath
    zincReportCachedProblems

$ ./mill -i dev.run example/basic/1-simple-scala -i inspect console # command with no args
console(ScalaModule.scala:369)
    Opens up a Scala console with your module and all dependencies present,
    for you to test and operate your code interactively.

Inputs:
    scalaVersion
    runClasspath
    scalaCompilerClasspath
    forkArgs
    forkEnv
    forkWorkingDir

$ ./mill -i dev.run example/basic/1-simple-scala -i inspect ivyDepsTree # command with lots of args
ivyDepsTree(JavaModule.scala:688)
    Command to print the transitive dependency tree to STDOUT.

    --inverse              Invert the tree representation, so that the root is on the bottom val
                           inverse (will be forced when used with whatDependsOn)
    --whatDependsOn <str>  Possible list of modules (org:artifact) to target in the tree in order to
                           see where a dependency stems from.
    --withCompile          Include the compile-time only dependencies (`compileIvyDeps`, provided
                           scope) into the tree.
    --withRuntime          Include the runtime dependencies (`runIvyDeps`, runtime scope) into the
                           tree.

Inputs:
    transitiveIvyDeps
    scalaVersion
    scalaVersion
    scalaOrganization
    scalaVersion

I also removed the numOverrides field on mill.define.Discover, since it's unused since #1600 landed a while back

inheritedIvyDeps.contains("Overriden ivyDeps Docs!!!"),
inheritedIvyDeps.contains("Any ivy dependencies you want to add to this Module")
globMatches(
"""core.test.ivyDeps(build.sc:...)
Copy link
Member Author

@lihaoyi lihaoyi May 16, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These tests are a bit fragile, but it's probably worth having at some some test where we assert on the overall shape of the inspect output rather than just looking for substrings. These docs and task inputs don't change very often anyway, so I expect the maintenance burden of keeping the tests up to date should be tolerable

@lefou lefou added the compat-breaker This PR is good to merge, but breaks compatibility and needs to wait till we prepare a major release label May 16, 2023
@lihaoyi lihaoyi requested a review from lefou May 16, 2023 06:24
@lihaoyi lihaoyi marked this pull request as ready for review May 16, 2023 06:24
@lihaoyi lihaoyi merged commit 156c7a4 into com-lihaoyi:main May 16, 2023
@lefou lefou added this to the 0.11.0-M9 milestone May 16, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
compat-breaker This PR is good to merge, but breaks compatibility and needs to wait till we prepare a major release
Projects
None yet
Development

Successfully merging this pull request may close these issues.

inspect should render a parameter usage help for commands
2 participants