Improve Documentation with Nullable

[sudosubin]

Objects represented via describe_object may have fields that are nullable.

Depending on the programming language (Python has None, TypeScript has null, Go has nil, etc) there are cases where this nullability is important, so it would be nice if nullable fields are well documented.

[chadlwilson]

Can you give a specific example of an API and fields you are talking about?

In general it seems basically none of the API docs go to the detail of saying which fields are always there, sometimes there and such.

[sudosubin]

For example, artifact config object's purge_settings could be null, and material attributes could hae null properties. (name, destination, filter, else)

Sometimes the field didn't exist at all and was parsed as null. I'm using python's pydantic for parsing the response, and pydantic actually works like this.

[chadlwilson]

I must confess that it's such an immense undertaking given the # of APIs and having to go back to first principles to figure it out - that I wouldn't know where to start (but agree with its usefulness and that it's a good practice that'd be required if, say, publishing a more technical API specification like an OpenAPI spec).

If there are some you have seen where it is documented, we could perhaps use that as a pattern to follow and start doing pieces incrementally.

[sudosubin]

Ideally, I believe that documentation should be generated automatically from code to reduce operation costs and be more accurate. (Using OpenAPI also helps auto-generate the client code.) However, it will be difficult to migrate because api.go.cd also has agent documentation and has a large amount of APIs.

If we take a light approach, after deciding how to display nullable properties as above coment, I think me and other contributors can fill in the missing details.