Issue with action creator documentation not displaying comments

Question

Issue with action creator documentation not displaying comments

We are exploring the possibility of integrating redux-toolkit into our application, but I am facing an issue with displaying the documentation comments for our action creators.

Here is our old code snippet:

const ADD_NAME = 'ADD_NAME';
/**
 * Sets the name for the user in our state.
 * @param name The updated name
 */
export function addName(name: string) {
   return {
     payload: name,
     type: ADD_NAME,
   };
}

In my VSCode environment, when I dispatch addName(), I can hover over the function to see the expected tooltip with the documentation.

Now, when trying to recreate this action creator using redux-toolkit:

/**
 * Sets the name for the user in our state.
 * @param name The updated name of the User
 */
export const addName = createAction<string>(ADD_NAME);

However, when hovering over the new addName during a dispatch, instead of seeing my written documentation:

Sets the name for the user in our state.

I encounter the following tooltip message:

Calling this {@link redux#ActionCreator} with an argument will return a {@link PayloadAction} of type T with a payload of P

This tooltip is generated from the internal documentation for ActionCreatorWithPayload within the redux-toolkit typings file.

My question is, why are the doc comments I added specifically for my addName action creator not being displayed, and instead, it shows the redux-toolkit doc comments?

Although one involves commenting a function and the other commenting a constant variable, I was expecting my comments for the addName constant to be reflected in the tooltip. What could I possibly be missing here?

typescript redux redux-toolkit

Answer 1

Answer №1

That's an excellent inquiry. The behavior described seems to vary depending on the text editor and the specific context in which the documentation is being accessed.

In the case of VSCode, it initially appears like this: https://i.stack.imgur.com/sZNpy.png

Simply typing 'addName' will display the docblock associated with the variable until completion. Once you add a '(', the editor delves into the value of the variable, recognizes the function, and retrieves the docblock from the function definition itself - typically an action creator.

As far as I know, it may not be possible to further alter this behavior, but I'm open to seeing if someone can propose an effective solution.

After conducting additional experiments, I found that although TypeScript may not preserve most comments for mapped function types, you could opt for using a single object argument instead of positional arguments and annotate the individual properties with relevant documentation blocks. This approach likely provides the maximum amount of information available within the constraints of TypeScript at present (alongside autocomplete functionality for the "argument names"):


const slice = createSlice({
  name: 'test',
  initialState: 0,
  reducers: {
    test: {
      prepare({name, age}: {
        /** Describes the name! */
        name: string,
        /** Represents the age! */
        age: number
      }
      ) {
        return { payload: { name, age } };
      },
      reducer(x, action: any) { }
    }
  }
})

// Hovering over 'age' or 'name' will provide additional insights
slice.actions.test({ age: 5, name: "" })

Answer 2

That's an excellent inquiry. The behavior described seems to vary depending on the text editor and the specific context in which the documentation is being accessed.

In the case of VSCode, it initially appears like this: https://i.stack.imgur.com/sZNpy.png

Simply typing 'addName' will display the docblock associated with the variable until completion. Once you add a '(', the editor delves into the value of the variable, recognizes the function, and retrieves the docblock from the function definition itself - typically an action creator.

As far as I know, it may not be possible to further alter this behavior, but I'm open to seeing if someone can propose an effective solution.

After conducting additional experiments, I found that although TypeScript may not preserve most comments for mapped function types, you could opt for using a single object argument instead of positional arguments and annotate the individual properties with relevant documentation blocks. This approach likely provides the maximum amount of information available within the constraints of TypeScript at present (alongside autocomplete functionality for the "argument names"):


const slice = createSlice({
  name: 'test',
  initialState: 0,
  reducers: {
    test: {
      prepare({name, age}: {
        /** Describes the name! */
        name: string,
        /** Represents the age! */
        age: number
      }
      ) {
        return { payload: { name, age } };
      },
      reducer(x, action: any) { }
    }
  }
})

// Hovering over 'age' or 'name' will provide additional insights
slice.actions.test({ age: 5, name: "" })

Issue with action creator documentation not displaying comments

Answer №1

Similar questions

Implementing basic authentication with AWS Lambda and Application Load Balancer

Dragula drag and drop in a single direction with Angular 2 copy functionality

Show Timing on the Y-Axis - Bubble Graph

The "in operator" is not compatible with string indexes

Create type declarations using the Typescript compiler by running the command:

Transmit information using express handlebars in a straightforward node application

Using TypeScript to utilize an enum that has been declared in a separate file

What types of arguments are typically sent to the component prop within redux-form?

Can you explain the concept of "Import trace for requested module" and provide instructions on how to resolve any issues that

Building a TypeScript Rest API with efficient routing, controllers, and classes for seamless management

Vue version 3 is encountering an issue with a module that does not have an exported member in the specified path of "../../node_modules/vue/dist/vue"

Preventing the occurrence of empty nested arrays within the state

Is it possible to launch a React application with a specific Redux state preloaded?

React-Redux - Implement a button toggle functionality to display or hide additional information

Using Typescript for the factory design pattern

What is the syntax for creating a zip function in TypeScript?

Establishing the initial state within the constructor of a React Component utilizing a generic state

Use TypeScript to cast the retrieved object from the local storage

Issue when trying to use both the name and value attributes in an input field simultaneously

Is there a way to trigger the click event in the week view of an Angular 2+ calendar?