ifconfig sample creates a poor impression

PowerShell / Crescendo

a module for wrapping native applications in a PowerShell function and module

MIT License

397 stars 37 forks source link

ifconfig sample creates a poor impression #152

Open jhoneill opened 2 years ago

jhoneill commented 2 years ago

It has place holders where help should be,
It doesn't parse output
It simply just turns ifconfig into invoke-ifconfig.

Why would anyone use it ? Several of the examples appear to turn command into invoke-command with longer parameter names (dd, ls, tar, who) without parsing the output.

theJasonHelmick commented 2 years ago

Thanks for the feedback @jhoneill. The samples are not intended to be complete solutions, rather samples of a particular feature or task. Having said that, I do agree that they can be improved, including some of the points you mention, to better help folks working with Crescendo.

jhoneill commented 2 years ago

@theJasonHelmick Yes, understood, but samples shipped with code should be really knock-your-socks-off examples; some of those included are good, and this one, TBH, just isn't.

JamesWTruher commented 2 years ago

I don't agree that all the samples should be knock-your-socks-off examples. very simple examples should also be present to show a complete story.

jhoneill commented 2 years ago

@JamesWTruher

YES, simple is good if it tells a story

Functionally this sample can be replaced with new-alias -Name Invoke-IfConfig -Value ifconfig

The json contains
"Description": "This is the description for a parameter",
which just looks like someone isn't trying.

JamesWTruher commented 2 years ago

I'll update the description. It doesn't matter if it can be replaced by an alias, that is not the point. It shows that a very simple example is possible.

theJasonHelmick commented 2 years ago

Thanks James (@jhoneill ). We are all trying. as mentioned, I'll go through and take a look at places we could add additional examples and improvements in a future milestone.