admittedly these weren’t the best before, without descriptions, but I think after this change they make a little less sense because the @param tag adds no information. for some of these it seems like they aren’t necessary, but then for ones like the @return tag it’s obvious they add value because the type of the return lacks explanatory power.

what are your thoughts on the tradeoffs between removing these altogether vs. taking advantage of the fact that we’re returning to these lines and finding a way to describe the parameters and return values?

e.g.

we could also expand the descriptions and make the tags more valuable

 /**
  * @param blockName Either the abbreviated core types, e.g. "paragraph", or the fully-qualitifed
  *                  block type with namespace and type, e.g. "core/paragraph" or "my-plugin/csv-table".
  */

on this note, I think if we add these back into the types at the top of the module, this documentation might track along with it and render much of these unnecessary 🤷‍♂️ 🤔

Just a quick note: removing the @param tags entirely isn't really an option in this case — they get auto-added back when the file is saved.

I removed the existing descriptions because I felt they weren’t particularly meaningful or helpful as-is. That said, I completely agree — adding thoughtful descriptions (especially for certain parameters and return values) can be really valuable for developers.

Also, regarding your point about defining types at the top of the module — while that's definitely useful for type safety and structure, adding inline descriptions there doesn’t help with IDE usability. Those descriptions won’t show up when hovering over function calls in editors like VS Code. By contrast, having @param and @return descriptions directly in the function JSDoc does provide helpful context in hover tooltips, like this:

Ref

Open to your thoughts on what makes the most sense here.

🤷‍♂️ now that you say it I think I’ve seen this before, where the IDE doesn’t bring along the documentation. I know it won’t for the params because the type docs explain the property while function arguments, even of the same type, are not required to actually be used in the same way.

there’s one more thing: did you try ParsedBlock['blockName'] instead of blockName? I can imagine these being different because in the existing case, it just so happens that they are both called the same thing, but ParsedBlock['blockName'] is a reference to the actual type in the definition above.

Ok, so I did give it a try, but it didn’t work out as expected — the descriptions don’t show up when hovering over the function. Here's what I tried:

1. Replaced the types with ParsedBlock[...]
2. Added comments where ParsedBlock is defined, describing each key.

function Block(
	blockName: ParsedBlock[ 'blockName' ],
	attrs: ParsedBlock[ 'attrs' ],
	innerBlocks: ParsedBlock[ 'innerBlocks' ],
	innerHTML: ParsedBlock[ 'innerHTML' ],
	innerContent: ParsedBlock[ 'innerContent' ]
): ParsedBlock {

Is it okay if we roll back to the approach you suggested earlier — adding the @param descriptions back in the function JSDoc itself? We can make the descriptions more vivid and helpful, which should improve the hover tooltips as well.

Something like this:

yes this seems reasonable, @im3dabasia — the descriptions are a bit redundant, but helpful. thank you so much for going through the process: I guess we know now what each construction allows and hides.

I've added descriptions for the parameters and return values. Please let me know if I’ve missed anything or if any of them could be improved.

Looking forward to your feedback!