cake-build / cake-build/cake

Provide ability to create documentation for Arguments similar to Tasks

Open
#1,708 3 comments 0 reactions 0 assignees View on GitHub
Feature Help wanted Up-for-grabs
Dominant language
C#
Stars
4.2k
Forks
778
Avg merge
1h 15m
Merged PRs (30d)
19

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:

Task                          Description

=============================================================
Default Default Task Description

Argument Description
=============================================================
--someArgument=<int> Argumentdescription.
Can be multiline, maybe. Defaults to x.

--someOtherargument=<string> Some other argument description

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

Open the contributing guide

Research direction

Start by reading the existing Argument methods and the -showdescription behavior described in the issue, then compare how task descriptions are registered and displayed. Done means arguments can carry optional help text and -showdescription presents those arguments alongside task descriptions, including multiline text and defaults.

Written by the indexing model from the issue text.

Assessment

Tech stack
csharp
Domain
cli
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.