Skip to content

Ship XML documentation files with the packages #3

Description

@BrewingCoder

None of the Tamp packages include an XML documentation file. Measured across a
populated package cache: 0 of 93 tamp package-versions contain any .xml doc
file
; lib/net10.0/ holds only the .dll.

The practical effect is that there is no IntelliSense, no parameter
documentation, and no way to learn the API surface short of reflecting over the
assemblies or decompiling them.

Concretely, this cost real time and produced a wrong conclusion:

  • I needed a target's plan sequence to keep running after one plan failed. I
    concluded the capability did not exist and reported to my team that it would
    need to be added to Tamp. It already existed as
    ITargetDefinition.FailureMode(FailureMode.Continue) in the version I was
    using.
  • Separately, I wanted to run a CommandPlan imperatively and handle its exit
    code. I looked for Run/Execute/RunAsync on CommandPlan, found none, and
    abandoned the approach. The escape hatch is Tamp.ProcessRunner.Execute(plan, stdout, stderr, targetName) and ProcessRunner.Capture(plan, ...), both
    public and static. I only found them by enumerating Core types that accept a
    CommandPlan parameter.

Both are discoverable in one glance with doc comments, and neither was
discoverable without writing a reflection harness.

Suggested fix: set <GenerateDocumentationFile>true</GenerateDocumentationFile>
and include the generated .xml alongside each .dll in the nupkg.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions