microsoft / microsoft/tsdoc

RFC: Support for @typeparam or @template for documenting generic parameters

Open
#72 8 comments 27 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

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

Description

In https://github.com/Microsoft/tsdoc/issues/8#issuecomment-424751850 @aciccarello wrote:

For a generic type definition, it can be helpful to document what the generic type is used for. Using @template was mentioned in some previous comments but I wonder if @typeparam would be better. Either way, I think this would be a good candidate for inclusion of the standard tags.

VS Code already has some support for @template and there has been a request for TypeDoc to support that as well (TypeStrong/typedoc#860). TypeDoc currently supports @typeparam T - Description and @param <T> - Description.

/**
 * Alias for array
 * 
 * @typeparam T - Type of objects the list contains
 */
type List<T> = Array<T>;

/**
 * Wrapper for an HTTP Response
 * @typeparam B - Response body
 * @param <H> - Headers
 */
interface HttpResponse<B, H> {
    body: B;
    headers: H;
    statusCode: number;
}

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 reviewing the linked TSDoc issue #8 discussion and the TypeDoc #860 reference, then compare the @typeparam, @template, and @param examples in this issue. Determine the standard syntax and semantics for generic-parameter documentation; done requires an agreed RFC direction rather than a localized edit.

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
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.