Adding a description for singular data tests and custom generic data tests

[dbeatty10]

Contributions

• I have read the contribution docs, and understand what's expected of me.

Link to the page on docs.getdbt.com requiring updates

Not sure exactly which pages -- something to determine based on the content below!

What part(s) of the page would you like to see updated?

Make sure there's an explanation in one or more places how to:

• add descriptions for definitions of custom generic data tests
• add descriptions for instances of singular data tests

Overview

There are two types of data tests:

1. Generic
2. Singular

We have two issues for adding description to data tests:

1. [spike] Allow generic data tests to be documented dbt-core#2578
2. [CT-3323] Allow singular tests to be documented dbt-core#9005 (comment)

A major difference between custom generic data tests and singular data tests is that the former can be re-used, but the latter can't.

So there are really three ways we could potentially add a description to data tests:

1. Definitions of generic data tests
2. Instances of generic data tests
3. Instances of singular data tests

(There's not a 4th option because there's only one instance per definition of a singular data test.)

Details

Generic data tests have one macro definition and then zero to many instances where they are used. So that's two different places we can imagine adding a description for generic data tests.

However, for singular data tests, there's one instance for each definition -- they are one-to-one. So there's only one description possible for that type of data test.

Descriptions for reusable definitions of generic data tests

Since the definition is just a macro, the definition of a custom generic data test can already have a description like this:

macros:
  - name: test_CUSTOM_GENERIC_TEST_NAME
    description: markdown_string
    arguments:
      - name: argument_name
        description: markdown_string

Descriptions for instances of generic data tests

However, I don't believe the instances of generic data tests can be documented until dbt-labs/dbt-core#2578 is implemented.

Descriptions for singular data tests

Added in dbt-labs/dbt-core#10792 to resolve dbt-labs/dbt-core#9005!

Additional information

See #5631 and #6191 for related issues.