`@deprecated` on property getter and setters.

🔎 Search Terms

deprecated, properties, getters, setters, tsdoc, jsdoc, merging

🕗 Version & Regression Information

• This changed between versions 5.0.4 and 5.1.6

---

Version behavior in playground sample

4.0.5 - 5.0.4: deprecated: test1, test2, test3, test4, not deprecated: test5
5.1.6 - nightly : deprecated: test1, test4, not deprecated: test2, test3, test5

⏯ Playground Link

https://www.typescriptlang.org/play/?ts=6.0.0-dev.20260108#code/MYGwhgzhAEAqCmEAu0DeAoaXoHoBUem20e0AAgCbwAOATvMGEvBdFXQ0y0dnjj9GoBXAEYgAlsGjNkARmgBeaAAYA3OgH5CxEtADi8JM1oDdlGvUbNW7S1wqm+A4WMnQA5oemIkAJgAUAJRo0PRIQrQAdiqq0AC+GsRajtAAyobGjvzELhJSEF4yfv4AbmAgQvAAXJFCALYi8LTBqAmaBCkGRk0p5hxWLGwWnNZZzqJ5HoU+AMxBIWER0Wrx467508hzZRXVtQ1NLW1JHTqkXZln5LYjgzcDDmfZ2LlunihFACzzqKGGSzFVu1tMRSOluiYrn07NYhv17NAChCxjkJm4kd5kN8dpUavVGs00MdsMkrhcek81pN3pikABWH5-cJRQHErCk0FpDIUznQ242YYPRHcyGg55YV4bD4+Bk4vb4w5EjRtYAAe0iyGk8iUkXgAHc4D4ggA6IqydRqjUfXyKaC6g0IZAmoq+C3qzVIGa2+2Gp2BU2zN1W6Sfb3631IZ0+T5Bj10sMOo3+op09ToH2OyPJnza6AzdQZpMB5A2pT59PhzNRra28uFv3FpChssFytFlO11RAA

💻 Code

class Test {
    /**
     * @deprecated deprecated
     */
    public test1 = 0;

    /**
     * Getter
     * @deprecated deprecated
     */
    public get test2() { return 0; }

    /**
     * Setter
     */
    public set test2(value:number) {}

    /**
     * Getter
     * @deprecated deprecated
     */
    public get test3() { return 0; }
    public set test3(value:number) {}

    /**
     * Getter
     * @deprecated deprecated
     */
    public get test4() { return 0; }

    /**
     * Setter
     * @deprecated deprecated setter
     */
    public set test4(value:number) {}

    /**
     * Getter
     */
    public get test5() { return 0; }

    /**
     * Setter
     * @deprecated deprecated setter
     */
    public set test5(value:number) {}

}

const t1 = new Test().test1;
const t2 = new Test().test2;
const t3 = new Test().test3;
const t4 = new Test().test4;
const t5 = new Test().test5;

new Test().test1 = 3;
new Test().test2 = 3;
new Test().test3 = 3;
new Test().test4 = 3;
new Test().test5 = 3;

🙁 Actual behavior

As per current behavior the TSDocs are merged for getters&setters of properties. This can be seen by hovering checking the documentation hovers of the elements.

But for test2, test3 and test5 the @deprecated tag has no effect and the elements are not marked as deprecated.

🙂 Expected behavior

Specific to the sample: The test2, test3 and test5 properties should be highlighted as deprecated (striked through) due to a @deprecated tag being present in the merged docs.

General: @deprecated marking should look at the JSDoc/TSDoc as also shown in the documentation overlays. Currently the shown docs and the deprecation are inconsistent. Either the documentation hints or the deprecated tags are broken?

Additional information about the issue

I found some issues and discussions around handling "getters" and "setters" separately in terms of docs. e.g. showing the setter doc when writing vs getter docs when accessing.

Especially https://github.com/microsoft/TypeScript/pull/37451 aimed to have contextual docs, but I cannot see that TS would have specific getter or setter docs based on usage as of today.

I'm not 100% about the current expectations around docs as is has quite an impact to overloads, inheritance etc. The TSDocs are currently merged in the displayed docs, same behavior for special tags like @deprecated.

---

My personal preference of an advanced behavior would be the following. But that's likely a more advanced feature implementation (out-of-scope) and not in-line with the current state of "contextual docs".

• If only the getter has a TSDoc, not the setter, the setter should inherit it (including deprecation tags). Use Case: you document the overall property once, like in C# the docs on property level.
• If only the setter has a TSDoc, not the getter, the getter should inherit it (including deprecation tags). Use Case: The setter might be more specific in terms of types, you prefer to document the overall property based on the setters to have a @param field to describe more detailed together with the overall property.
• If both the getter and the setter have TSDocs the documentation and deprecation depends on the exact usage (reading or writing). Use Case: you have different behaviors on getters and setters. e.g. only the getter or setter is deprecated in favor of something else. This similar to having C# attributes on get; or set; level.

---

Some issues I found around this topic:

• https://github.com/microsoft/TypeScript/issues/58167
• https://github.com/microsoft/TypeScript/issues/20966
• https://github.com/microsoft/TypeScript/issues/48801

Start with the linked TypeScript Playground sample and trace how getter and setter JSDoc is merged with deprecation handling. Compare the behavior of test2, test3, and test5 with the expected property diagnostics; done means merged documentation and @deprecated markings are consistent.