implement deprecated

[thepassle]

https://github.com/webcomponents/custom-elements-manifest/pull/89

[thepassle]

This is probably easy to add by adding it to the handleJsDoc function, which is used pretty much everywhere for jsdoc https://github.com/open-wc/custom-elements-manifest/blob/master/packages/analyzer/src/features/analyse-phase/creators/handlers.js#L39

[kateutlik]

I am working on this issue

[WickyNilliams]

A quick plugin i whipped up which seems to do the trick:

function deprecatedPlugin() {
  function isDeprecated(node) {
    return node?.jsDoc?.some(doc => doc?.tags?.find(tag => tag.tagName.getText() === "deprecated"))
  }

  return {
    name: "deprecated-plugin",

    analyzePhase({ ts, node, moduleDoc }) {
      if (!ts.isClassDeclaration(node)) {
        return
      }

      const className = node.name.getText()
      const classDeclaration = moduleDoc.declarations.find(declaration => declaration.name === className)

      // classes can be deprecated
      if (isDeprecated(node)) {
        classDeclaration.deprecated = true
      }

      // as can individual members
      node.members?.forEach(member => {
        if (isDeprecated(member)) {
          const memberName = member.name.getText()
          const field = classDeclaration.members.find(m => m.name === memberName)
          field.deprecated = true
        }
      })
    },
  }
}

Playground example

[thepassle]

Nice 🙂 That will enable anybody who is currently interested in this feature to already support it in their projects via the plugin. Ideally, we'd still add it the handleJsDoc. @kateutlik did you make any progress on this?

[WickyNilliams]

agreed, would be great if it was supported out of the box. i was surprised it wasn't.

btw is there any way to improve the plugin above? it feels weird to me to wait for class nodes, then loops through its members. vs processing each node as-is. it'd be nice if there was a util like getDocsForNode so the code could be like:

analyzePhase({ ts, node, moduleDoc }) {
  if (isDeprecated(node)) {
    const docNode = getDocsForNode(moduleDoc, node) // returns relevant class or member
    docNode?.deprecated = true
  }
}

maybe i'm missing something :) i don't have much experience working with ASTs

[kateutlik]

I have implemented a deprecated tag for methods, here is the PR: https://github.com/open-wc/custom-elements-manifest/pull/174 @thepassle do I need to implement the same for the class notation?

[thepassle]

Ah good catch, yes please 😊

[kateutlik]

Added handler for a deprecated tag for classes as well, here is the PR: https://github.com/open-wc/custom-elements-manifest/pull/174 @thepassle could you please review?

[thepassle]

closed via #174 , thanks for the contribution @kateutlik !