docs(cli): improve spinner.message document

[andrewthauer]

This makes the Spinner in @std/cli expose a message property to be consistent with the existing color property. It also adds doc comments and an examples for both message and color

NOTE: I noticed another issue while making this change. The Color type also includes Ansi which is defined as a string. However, the actual code in the set color property will never let you set this to anything other then a valid COLORS value.

[CLAassistant]

All committers have signed the CLA.

[kt3k]

Changing message seems already supported? See #4079

[andrewthauer]

Changing message seems already supported? See #4079

That's correct. The feature is already available. I've updated the commit message and PR title to better reflect the change.

Reason - I did not realize you could change message initially which led me to look at the code and realized it was a public field and not a property like color is. The documentation in jsr for fields isn't as clearly noticeable atm (separate issue).

So, I figured it would make more sense to use a formal property here so it's both consistent with color and has some documentation. I've also added docs for the existing color property methods too.

[kt3k]

This sounds rather doc issue, or UI issue of JSR. message property doc appears in JSR https://jsr.io/@std/cli/doc/spinner/~/Spinner#property_message . So changing message to getter/setter seems like increasing unnecessary boilerplate.

How about updating the API doc of message property (Probably adding the @example of the current set message doc)?

[andrewthauer]

This sounds rather doc issue, or UI issue of JSR. message property doc appears in JSR https://jsr.io/@std/cli/doc/spinner/~/Spinner#property_message . So changing message to getter/setter seems like increasing unnecessary boilerplate.

How about updating the API doc of message property (Probably adding the @example of the current set message doc)?

To me this is more about consistency and readability of the class. The act of creating a property screams this is meant to be public. Where, a field could just be something you accidentally forgot to make private explicitly. Also, fields tend to be located at the top which then makes interlacing larger comments between fields a bit unwieldy imo.

Another thing that is potentially an issue is usage of constructor(public someField: string). It doesn't appear someField is easily document-able as far as I can tell. This might be something for consideration.

Anyways, I looked around and see there is some precedence for making fields public already. I'm happy to comment the field versus making is a property. If any of my thoughts resonate let me know and I'm happy to adjust.

An interesting note here is that LSP's seem to show both the same (property in vscode & field in neovim), but jsr distinguishes field & property differently.

[codecov]

Codecov Report

Attention: Patch coverage is 78.57143% with 3 lines in your changes are missing coverage. Please review.

Project coverage is 91.97%. Comparing base (082107b) to head (65f5a8e).

Files	Patch %	Lines
cli/spinner.ts	78.57%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4785      +/-   ##
==========================================
- Coverage   91.97%   91.97%   -0.01%     
==========================================
  Files         487      487              
  Lines       41539    41542       +3     
  Branches     5365     5365              
==========================================
+ Hits        38207    38208       +1     
- Misses       3274     3276       +2     
  Partials       58       58              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[kt3k]

Nice docs! LGTM

[andrewthauer]

Just realized this should be console.log since setting the message after stop won't do anything. I'll fix!

[kt3k]

LGTM again. Thanks for your contribution!