microsoft / microsoft/tsdoc

Callable variables and class properties

Open
#65 1 comment 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

general discussion
Dominant language
TypeScript
Stars
5k
Forks
162
Avg merge
17h 24m
Merged PRs (30d)
8

Description

An interesting use-case came up in the TypeDoc repo (TypeStrong/typedoc#858). Would it be reasonable to define the following as a function rather than a variable? JSDoc users can use @function but from discussions in #8 I don't know if that would be a good thing to carryover.

/**
 * Promisified version of fs.writeFile().
 * @function writeFileAsync
 */
export const writeFileAsync: Function = util.promisify(fs.writeFile);

A similar use case is instance methods. I know that tslint has made changes to view these the same as methods for the purpose of grouping properties and methods.

class Foo {
  constuctor(events: EventService) {
    events.on('someevent', this.bar);
  }


  /**
   * This acts like a method and can be passed as a callback without losing context of `this`.
   * @param param - new value of prop
   */
  bar = (param: String) => {
    console.log('Am I a method?');
    this.prop = param;
  }
}

Contributor guide

No contributing guide indexed for this repository

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 by reading the linked TypeDoc issue TypeStrong/typedoc#858 and the discussions in #8, then compare the callable-variable and instance-property examples in this issue. Done would require a settled specification decision on whether these constructs are treated like functions or methods and how their documentation should be represented.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.