typedoc2md / typedoc-plugin-markdown

A plugin for TypeDoc that enables TypeScript API documentation to be generated in Markdown.
https://typedoc-plugin-markdown.org
MIT License
725 stars 177 forks source link

When both a getter and a setter are defined, the return sections are not rendered correctly #711

Closed ilg-ul closed 2 weeks ago

ilg-ul commented 3 weeks ago

What package is the bug related to?

typedoc-plugin-markdown

Describe the issue

I have a class with an accessor (logger) that has both get and set methods.

The Return of the getter is rendered at the end, as like being the return of the setter, and the return of the setter is not rendered:

Screenshot 2024-10-31 at 12 35 14

TypeDoc configuration

    [
      'docusaurus-plugin-typedoc',
      {
        // https://typedoc-plugin-markdown.org/docs/options#display-options
        blockTagsPreserveOrder: [
          "@example"
        ],
        categorizeByGroup: false, // Otherwise it fails to load sidebar.
        classPropertiesFormat: "list", // "table" not, it may have examples
        entryPointStrategy: "resolve",
        entryPoints: [
          "../src/index.ts"
        ],
        enumMembersFormat: "table",
        excludeExternals: true,
        excludeInternal: true,
        expandObjects: true,
        expandParameters: true,
        indexFormat: "table",
        interfacePropertiesFormat: "list", // "table" not, it may have examples
        logLevel: "Verbose",
        parametersFormat: "table",
        plugin: [
          "typedoc-plugin-markdown"
        ],
        propertyMembersFormat: "table",
        readme: "none",
        skipErrorChecking: true,
        sort: [
          "instance-first",
          "visibility"
        ],
        tsconfig: '../tsconfig.json',
        "tableColumnSettings": {
          "leftAlignHeaders": true
        },
        typeDeclarationFormat: "table",
        useCodeBlocks: false, // Nice, but it might be mistaken for examples.
      }
    ],

Expected behavior

Two return sections:

Screenshot 2024-10-31 at 12 39 14

tgreyuk commented 3 weeks ago

Thanks.

In order to fix this properly I have introduced new headings "Get Signature" and "Set Signature" (these are localized typedoc strings). These additional headings are required to maintain the semantic integrity of heading levels, but also I think it clearly convey that each block documents the method signature for getting or setting a property, making it immediately obvious to readers.

Hopefully this is acceptable - fix in typedoc-plugin-markdown@4.2.10

Screenshot 2024-11-01 at 23 03 53
linrongbin16 commented 3 weeks ago

This issue is almost the same with my previous issue (I should not close it): https://github.com/typedoc2md/typedoc-plugin-markdown/issues/701

ilg-ul commented 2 weeks ago

In order to fix this properly I have introduced new headings "Get Signature" and "Set Signature" (these are localized typedoc strings).

Great!

Could you check if those headings are also rendered properly when the accessors are part of a category/group?

tgreyuk commented 2 weeks ago

Yes - seems to be good. Being part of a category/group shouldn't effect the behaviour - well I hope not anyway :).

ilg-ul commented 2 weeks ago

I confirm that the latest release solved this issue.

Thank you for the quick fix.