jsdoc / jsdoc/jsdoc

Clarify @interface on types that can be used

Open
#1,547 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
JavaScript
Stars
15.5k
Forks
1.5k
Avg merge
10d 23h
Merged PRs (30d)
1

Description

Expected behavior

If @interface can be used on plain objects as well as classes, call this out explicitly in the docs.

Current behavior

While the docs do state things seemingly generically, i.e.,:

The @interface tag marks a symbol as an interface that other symbols can implement. For example, your code might define a parent class...

...given the insistence by JSDoc that other tags work with classes only (e.g., @event), I think it'd be helpful to call out explicitly that an interface can be an object, or if possible, a function or other types.

Your environment
Software Version
JSDoc 3.5.5
Node.js 9.2.1
npm 6.1.0
Operating system Mac OSX

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the @interface documentation and compare its wording with the documented behavior of related tags such as @event. Determine which symbol types are supported, then update the relevant documentation so the supported types and any limits are explicit. Verify the rendered documentation answers whether plain objects, classes, functions, or other types can be used.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.