search

google / blockly

The web-based visual programming editor.
https://developers.google.com/blockly/
Apache License 2.0
12.43k stars 3.71k forks source link

Method reference docs are missing descriptions #7244

Open BeksOmega opened 1 year ago

BeksOmega commented 1 year ago

Location

e.g. https://developers.google.com/blockly/reference/js/blockly.icons_namespace.commenticon_class.md

Type

Suggested content

The reference docs only put method descriptions if the direct JSDoc has a description. This means that we are missing descriptions if: 1) We are overriding a function - the description should be inheritted but is not. 2) We only have an @return tag with no description - the @return tag should be used as the description.

Additional context

There are several solutions to this problem:

1) Patch API documenter. We already patch API documenter so we could also patch it to fix this issue.

2) Fork API documenter. They state in their dev docs that "The api-documenter project was designed to serve as a code sample", so continually patching sample code feels like not the happy path. So it might also be worth it to just create our own documenter, so we don't have to keep maintaining patches.

3) Use someone else's API documenter, such as firebase's.

4) Change the lint config to require descriptions.

maribethb commented 1 year ago

Let's talk about this before you do any work on it.