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

What are the benefits of utilizing TypeScript declarations? How can you demonstrate their value with concrete examples?

unable to successfully complete parameter in angular 2

Holding off on completing a task until the outcomes of two parallel API requests are received

Get rid of the TypeScript error in the specified function

Using Angular to dynamically access component properties

Receiving a conduit from the fuel supplier with only limited information on hand

Need for utilizing a decorator when implementing an interface

Hide the MaterialTopTabNavigator from view

RTK Query may sometimes encounter undefined values when fetching data

The classification of a property is determined by the types of the other properties present

Exploring the power of a mapped type within a tuple

How do I iterate through my state in React Redux?

Is Typescript familiar with the import -> require syntax, but unfamiliar with the require -> import syntax?

Transfer items on a list by dragging and dropping them onto the navigation label of the target component

Incorporating Firebase administrator into an Angular 4 project

Exploring alternative applications of defineModel in Vue 3.4 beyond just handling inputs

Maintain the specific type based on the provided data, rather than the default value, when a related generic is defined

Error encountered while implementing onMutate function in React Query for Optimistic Updates

Ways to specify an unused parameter within a function

Looking to reallocate information, paginate, and sort each time a new row is added to the mat-table