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, concise responsibilities. Comments that only restate the names of variables add nothing to code, and can easily become outdated.

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"
  • "functions" "methods" may also specify "overloads" to indicate that each overload should have its own documentation, which is false by default.
  • 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"
• "constructors"
• "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"
          },
          "constructors": {
            "properties": {
              "tags": {
                "properties": {
                  "content": {
                    "items": {
                      "type": "string"
                    },
                    "type": "object"
                  },
                  "existence": {
                    "items": {
                      "type": "string"
                    },
                    "type": "array"
                  }
                }
              },
              "privacies": {
                "enum": [
                  "all",
                  "private",
                  "protected",
                  "public"
                ],
                "type": "string"
              },
              "overloads": {
                "type": "boolean"
              }
            },
            "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"
              },
              "overloads": {
                "type": "boolean"
              }
            },
            "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"
              },
              "overloads": {
                "type": "boolean"
              }
            },
            "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"
          }
        }
      }
    ]
  }
}