doc: add annotation to writeFile data as Object

[JakobJingleheimer]

Fixes: #39152

[aduh95]

I'm not sure using * is a great idea, I don't think we're using this anywhere else, and I personally find it confusing. You could simply put the info in the body of the docs, like this:

node/doc/api/buffer.md

Line 695 in f4d0a6a

A `TypeError` will be thrown if `size` is not a number.

[JakobJingleheimer]

Consolidating the various * threads to the main discussion so they don't get lost:

Sorry, I didn't mean a literal asterisk.

Oh 😅

I would just add the language used in #34993

@mscdex@aduh95 I included the footnote marker instead of duplicating the wording everywhere so it could be consolidated (since it probably has a single implementation source under the hood—meaning they would all change together).

Putting myself in the user's shoes, I figure if I saw … | <Stream> | <Object>*, I would put together that there is some note somewhere specifically related to data as an Object. Since writeFileSync()'s description basically just directs to writeFile() but had no note, I would follow the redirect to writeFile and expect to find it there (and there it indeed is).

Regarding the * itself, I think it's important to have some kind of visual cue on/near the type defs so a user will see it and know there's something to look for; just chucking a gotcha in the body seems insufficient to me. Without, I think it would be reasonable for a user who is only looking to see what types can be used for an argument to look only at the type def, see nothing, and stop here.

In terms of which marker to use, my preference would be superscript numbers because it's robust (supporting an unlimited number of them, whereas symbols like ^*†‡ quickly run out). So something like:

foo {string} ¹ Tellus mauris a diam maecenas.
bar {Buffer|Stream|Object} ² Velit aliquet sagittis id consectetur.
Ultrices in iaculis nunc sed augue. Ipsum suspendisse ultrices gravida dictum
fusce ut placerat orci nulla. Nec nam aliquam sem et tortor consequat id porta.
Nibh tellus molestie nunc non blandit massa. Pharetra massa massa ultricies mi.
Netus et malesuada fames ac turpis egestas integer.
1. The first footnote here
2. The second footnote here

[mscdex]

instead of duplicating the wording everywhere

IMO I don't think that's a problem. There is a lot of duplicated wording in various sections of the node docs.

In general I think it's no different than clarifying anything else about the signature or behavior of various APIs. The end user will need to be reading the function description anyway. If we're going to be changing how we convey certain types of information in the node API documentation, we should probably do so on a wider scale with a solid plan. For now though I think it's enough to just add the missing wording where necessary, even if it's duplicated.

[JakobJingleheimer]

The end user will need to be reading the function description anyway.

That is not true for the example I gave above.

But yes, I agree: if there is no precedent for footnotes, best not to start randomly now. I'll update to duplicating the wording and leave the DRYing for later.

[JakobJingleheimer]

I'm not sure if this is applicable, but Object is listed in the types, so I guessed yes. Wanted to specifically call out just in case.

[JakobJingleheimer]

nudge @mscdex@aduh95

[JakobJingleheimer]

@aduh95 🙏 I don't have access to merge PRs yet (not until after my first PR lands, if I recall correctly). Could you assist?

[github-actions]

Landed in 9257372...6a4b4ce