Ignore `@public` members in `vue/no-unused-properties`

[FloEdelmann]

What rule do you want to change?
vue/no-unused-properties

Does this change cause the rule to produce more or fewer warnings?
Fewer

How will the change be implemented? (New option, new default behavior, etc.)?
It can either be the new default behavior, or enabled via a ignorePublicMembers option that is false by default.

Please provide some example code that this change will affect:

<template>
  <div>(nothing is used here)</div>
</template>

<script>
export default {
  name: 'MySampleComponent',
  data() {
    return {
      /** @public */
      publicData: 'someData',
    };
  },
  computed: {
    /**
     * @public
     */
    publicComputed() {
      return 'someComputedValue';
    },
  },
  methods: {
    /**
     * @public
     */
    publicMethod() {
    },
  },
};
</script>

What does the rule currently do for this code?
It warns that neither publicData nor publicComputed nor publicMethod are used.

What will the rule do after it's changed?
Not warn, because they are marked as @public in the respective JSDoc comments.

Additional context
Marking them as public can be used to specify that they are not used inside the component, but from outside via $ref:

<template>
  <MySampleComponent ref="sample" />
</template>

<script>
export default {
  mounted() {
    console.log(this.$refs.sample.publicData); // 'someData'
    console.log(this.$refs.sample.publicComputed); // 'someComputedValue'
    console.log(this.$refs.sample.publicMethod); // function
  },
}
</script>

[ota-meshi]

Thank you for posting this issue.

I like your idea, but is that @public comment available for tools other than eslint-plugin-vue, and is that tool popular?
(As far as I know, @public is not available in .vue with JSDoc.)
If that popular tool doesn't exist, you can mark it with // eslint-disable-next-line vue/no-unused-properties -- this is public.

What do you think?

[FloEdelmann]

The @public tag is officially supported in JSDoc: https://jsdoc.app/tags-public.html

For now, I've disabled the rule manually with a comment like you've suggested. But I think that adding a JSDoc comment would be more descriptive.

[ota-meshi]

Does JSDoc documentation generator work well based on the JSDoc comments described in .vue?
I have never seen it. If possible would you please share the JSDoc generated documentation?

[FloEdelmann]

There is documentation.js which seems to support JSDoc in Vue. I must admit that I don't generate documentation from my Vue components yet, so I can't tell which tool does support it. But I still find the JSDoc syntax easy to write and read in .vue files.

[ota-meshi]

I think it's great that the documentation generator or type checker and eslint-plugin-vue can be handled using the same markers.
But I don't know about them, so I want to make sure it works.

[FloEdelmann]

There is another tool, Vue Styleguidist, that uses the @public tag exactly like I've suggested: https://vue-styleguidist.github.io/docs/Documenting.html#public-methods

This example documentation is generated from this source code and includes the set() method because it is marked as @public.

[ota-meshi]

Thank you for letting me know. It's great to be able to use @public.

[aggmoulik]

Hy @ota-meshi , Do the issue here referring to add another option ignorePublicMembers ? Can I be clear before working on this issue ?

[aggmoulik]

For the record, I have used above example and I am not getting any error as it is passing very well.

[FloEdelmann]

@aggmoulik Did you explicitly enable the vue/no-unused-properties rule? It is not included in any sharable config:

"vue/no-unused-properties": ["error", {
  "groups": ["props", "data", "computed", "methods", "setup"]
}],

@ota-meshi Should ignoring @public members be the default, or should it be explicitly enabled with a new ignorePublicMembers rule option?

[ota-meshi]

I think the default for ignorePublicMembers should be false, because it only checks props by default. Maybe people don't use @public for props.

[FloEdelmann]

For anyone trying to pick this up, here's a diff for the rule documentation and test changes:

Diff

diff --git a/docs/rules/no-unused-properties.md b/docs/rules/no-unused-properties.md
index 932fb95..df2ab54 100644
--- a/docs/rules/no-unused-properties.md
+++ b/docs/rules/no-unused-properties.md
@@ -55,7 +55,8 @@ This rule cannot be checked for use in other components (e.g. `mixins`, Property
 {
   "vue/no-unused-properties": ["error", {
     "groups": ["props"],
-    "deepData": false
+    "deepData": false,
+    "ignorePublicMembers": false
   }]
 }
 ```
@@ -67,6 +68,7 @@ This rule cannot be checked for use in other components (e.g. `mixins`, Property
   - `"methods"`
   - `"setup"`
 - `"deepData"` (`boolean`) If `true`, the object of the property defined in `data` will be searched deeply. Default is `false`. Include `"data"` in `groups` to use this option.
+- `"ignorePublicMembers"` (`boolean`) If `true`, members marked with a [JSDoc `/** @public */` tag](https://jsdoc.app/tags-public.html) will be ignored. Default is `false`.
 
 ### `"groups": ["props", "data"]`
 
@@ -188,6 +190,34 @@ This rule cannot be checked for use in other components (e.g. `mixins`, Property
 
 </eslint-code-block>
 
+### `{ "groups": ["props", "methods"], "ignorePublicMembers": true }`
+
+<eslint-code-block :rules="{'vue/no-unused-properties': ['error', {groups: ['props', 'methods'], ignorePublicMembers: true}]}">
+
+```vue
+<!-- ✓ GOOD -->
+<template>
+  <button @click="usedInTemplate()" />
+</template>
+<script>
+  export default {
+    methods: {
+      /* ✓ GOOD */
+      usedInTemplate() {},
+      
+      /* ✓ GOOD */
+      /** @public */
+      publicMethod() {},
+      
+      /* ✗ BAD */
+      unusedMethod() {}
+    }
+  }
+</script>
+```
+
+</eslint-code-block>
+
 ## :rocket: Version
 
 This rule was introduced in eslint-plugin-vue v7.0.0
diff --git a/lib/rules/no-unused-properties.js b/lib/rules/no-unused-properties.js
index 61ac835..f732780 100644
--- a/lib/rules/no-unused-properties.js
+++ b/lib/rules/no-unused-properties.js
@@ -490,7 +490,8 @@ module.exports = {
             additionalItems: false,
             uniqueItems: true
           },
-          deepData: { type: 'boolean' }
+          deepData: { type: 'boolean' },
+          ignorePublicMembers: { type: 'boolean' }
         },
         additionalProperties: false
       }
diff --git a/tests/lib/rules/no-unused-properties.js b/tests/lib/rules/no-unused-properties.js
index 89478e0..1efe0de 100644
--- a/tests/lib/rules/no-unused-properties.js
+++ b/tests/lib/rules/no-unused-properties.js
@@ -1411,6 +1411,68 @@ tester.run('no-unused-properties', rule, {
         </script>
       `,
       options: deepDataOptions
+    },
+
+    // ignore public members
+    {
+      filename: 'test.vue',
+      code: `
+        <script>
+        export default {
+          data: () => ({
+            /** @public */
+            publicData: 'foo'
+          })
+        }
+        </script>
+      `,
+      options: [{ groups: ['data'], ignorePublicMembers: true }]
+    },
+    {
+      filename: 'test.vue',
+      code: `
+        <script>
+        export default {
+          computed: {
+            /** @public */
+            unusedComputed() {
+              return 'foo'
+            }
+          }
+        }
+        </script>
+      `,
+      options: [{ groups: ['computed'], ignorePublicMembers: true }]
+    },
+    {
+      filename: 'test.vue',
+      code: `
+        <script>
+        export default {
+          methods: {
+            /** @public */
+            publicMethod() {}
+          }
+        }
+        </script>
+      `,
+      options: [{ groups: ['methods'], ignorePublicMembers: true }]
+    },
+    {
+      filename: 'test.vue',
+      code: `
+        <script>
+        export default {
+          setup() {
+            return {
+              /** @public */
+              publicRef: 3
+            }
+          }
+        }
+        </script>
+      `,
+      options: [{ groups: ['setup'], ignorePublicMembers: true }]
     }
   ],

ignore-public-members.diff.txt