Rule: completed-docs

Enforces JSDoc comments for important items be filled out.

Rationale

Helps ensure important components are documented.

Note: use this rule sparingly. It’s better to have self-documenting names on components with single, consice responsibilities. Comments that only restate the names of variables add nothing to code, and can easily become outdated.

Notes:

Config

true to enable for [classes, functions, methods, properties], or an array with each item in one of two formats:

  • string to enable for that type
  • object keying types to when their documentation is required:
    • "methods" and "properties" may specify:
      • "privacies":
        • "all"
        • "private"
        • "protected"
        • "public"
      • "locations":
        • "all"
        • "instance"
        • "static"
    • Other types may specify "visibilities":
      • "all"
      • "exported"
      • "internal"
    • All types may also provide "tags" with members specifying tags that allow the docs to not have a body.
      • "content": Object mapping tags to RegExp bodies content allowed to count as complete docs.
      • "existence": Array of tags that must only exist to count as complete docs.

Types that may be enabled are:

  • "classes"
  • "enums"
  • "enum-members"
  • "functions"
  • "interfaces"
  • "methods"
  • "namespaces"
  • "properties"
  • "types"
  • "variables"
Config examples
"completed-docs": true
"completed-docs": [true, "enums", "functions", "methods"]
"completed-docs": [
  true,
  {
    "enums": true,
    "functions": {"visibilities": ["exported"]},
    "methods": {"locations": "instance", "privacies": ["public", "protected"]},
    "properties": {
      "tags": {"content": {"see": ["#.*"]}, "existence": ["inheritdoc"]}
    }
  }
]
Schema
{
  "type": "array",
  "items": {
    "anyOf": [
      {
        "options": [
          "classes",
          "enums",
          "functions",
          "interfaces",
          "methods",
          "namespaces",
          "properties",
          "types",
          "variables"
        ],
        "type": "string"
      },
      {
        "type": "object",
        "properties": {
          "classes": {
            "properties": {
              "tags": {
                "properties": {
                  "content": {
                    "items": {
                      "type": "string"
                    },
                    "type": "object"
                  },
                  "existence": {
                    "items": {
                      "type": "string"
                    },
                    "type": "array"
                  }
                }
              },
              "visibilities": {
                "enum": [
                  "all",
                  "exported",
                  "internal"
                ],
                "type": "string"
              }
            },
            "type": "object"
          },
          "enums": {
            "properties": {
              "tags": {
                "properties": {
                  "content": {
                    "items": {
                      "type": "string"
                    },
                    "type": "object"
                  },
                  "existence": {
                    "items": {
                      "type": "string"
                    },
                    "type": "array"
                  }
                }
              },
              "visibilities": {
                "enum": [
                  "all",
                  "exported",
                  "internal"
                ],
                "type": "string"
              }
            },
            "type": "object"
          },
          "enum-members": {
            "properties": {
              "tags": {
                "properties": {
                  "content": {
                    "items": {
                      "type": "string"
                    },
                    "type": "object"
                  },
                  "existence": {
                    "items": {
                      "type": "string"
                    },
                    "type": "array"
                  }
                }
              },
              "visibilities": {
                "enum": [
                  "all",
                  "exported",
                  "internal"
                ],
                "type": "string"
              }
            },
            "type": "object"
          },
          "functions": {
            "properties": {
              "tags": {
                "properties": {
                  "content": {
                    "items": {
                      "type": "string"
                    },
                    "type": "object"
                  },
                  "existence": {
                    "items": {
                      "type": "string"
                    },
                    "type": "array"
                  }
                }
              },
              "visibilities": {
                "enum": [
                  "all",
                  "exported",
                  "internal"
                ],
                "type": "string"
              }
            },
            "type": "object"
          },
          "interfaces": {
            "properties": {
              "tags": {
                "properties": {
                  "content": {
                    "items": {
                      "type": "string"
                    },
                    "type": "object"
                  },
                  "existence": {
                    "items": {
                      "type": "string"
                    },
                    "type": "array"
                  }
                }
              },
              "visibilities": {
                "enum": [
                  "all",
                  "exported",
                  "internal"
                ],
                "type": "string"
              }
            },
            "type": "object"
          },
          "methods": {
            "properties": {
              "tags": {
                "properties": {
                  "content": {
                    "items": {
                      "type": "string"
                    },
                    "type": "object"
                  },
                  "existence": {
                    "items": {
                      "type": "string"
                    },
                    "type": "array"
                  }
                }
              },
              "locations": {
                "enum": [
                  "all",
                  "instance",
                  "static"
                ],
                "type": "string"
              },
              "privacies": {
                "enum": [
                  "all",
                  "private",
                  "protected",
                  "public"
                ],
                "type": "string"
              }
            },
            "type": "object"
          },
          "namespaces": {
            "properties": {
              "tags": {
                "properties": {
                  "content": {
                    "items": {
                      "type": "string"
                    },
                    "type": "object"
                  },
                  "existence": {
                    "items": {
                      "type": "string"
                    },
                    "type": "array"
                  }
                }
              },
              "visibilities": {
                "enum": [
                  "all",
                  "exported",
                  "internal"
                ],
                "type": "string"
              }
            },
            "type": "object"
          },
          "properties": {
            "properties": {
              "tags": {
                "properties": {
                  "content": {
                    "items": {
                      "type": "string"
                    },
                    "type": "object"
                  },
                  "existence": {
                    "items": {
                      "type": "string"
                    },
                    "type": "array"
                  }
                }
              },
              "locations": {
                "enum": [
                  "all",
                  "instance",
                  "static"
                ],
                "type": "string"
              },
              "privacies": {
                "enum": [
                  "all",
                  "private",
                  "protected",
                  "public"
                ],
                "type": "string"
              }
            },
            "type": "object"
          },
          "types": {
            "properties": {
              "tags": {
                "properties": {
                  "content": {
                    "items": {
                      "type": "string"
                    },
                    "type": "object"
                  },
                  "existence": {
                    "items": {
                      "type": "string"
                    },
                    "type": "array"
                  }
                }
              },
              "visibilities": {
                "enum": [
                  "all",
                  "exported",
                  "internal"
                ],
                "type": "string"
              }
            },
            "type": "object"
          },
          "variables": {
            "properties": {
              "tags": {
                "properties": {
                  "content": {
                    "items": {
                      "type": "string"
                    },
                    "type": "object"
                  },
                  "existence": {
                    "items": {
                      "type": "string"
                    },
                    "type": "array"
                  }
                }
              },
              "visibilities": {
                "enum": [
                  "all",
                  "exported",
                  "internal"
                ],
                "type": "string"
              }
            },
            "type": "object"
          }
        }
      }
    ]
  }
}