cake-build/cake

Provide ability to create documentation for Arguments similar to Tasks

Open

#1,708 opened on Jul 31, 2017

View on GitHub
 (3 comments) (0 reactions) (0 assignees)C# (738 forks)batch import
FeatureHelp wantedUp-for-grabs

Repository metrics

Stars
 (3,742 stars)
PR merge metrics
 (Avg merge 1d 1h) (25 merged PRs in 30d)

Description

Hi,

as described in this SO question: https://stackoverflow.com/questions/45413524/how-can-cake-build-arguments-be-documented it would be great to be able to add documentation for Arguments as it is currently possible for Tasks by using the Description("...") method.

So e.g. executing the build script with the -showdescription parameter could show the described targets as well as the available arguments with an optional help text:

For registering a help text with an argument an additional parameter could be introduced to the already existing Argument methods. E.g.

Argument("someArgument", "x", "Argument description. Can be multiline, maybe.")

Or some other way:

var argValue = ArgumentBuilder("someArgument", "x")
                              .WithHelpText("Argument description. Can be multiline, maybe.")
                              .GetValue()

What do you think?

Best regards, Philipp

Contributor guide

Research direction
Examine how Task.Description is implemented and replicate similar pattern for Arguments. Look at existing Argument methods and extend them with a description parameter.
Tech stack
csharp
Domain
build system
Issue type
Feature
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
2
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-3 hours
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
Active
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
Clear
Prerequisites
C#Git
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
75