Enhance tiledb.cloud.dag module typing and documentation

[spencerseale]

Add class doc str to Node and DAG so they're built into API ref: https://tiledb-inc.github.io/TileDB-Cloud-Py/reference/dag.dag.html

Original slack: https://tiledb.slack.com/archives/CB0NNLS6B/p1720713156703479

[JohnMoutafis]

@spencerseale Have you tested with quartodoc locally how the docstrings will appear in the docs?

[spencerseale]

@spencerseale Have you tested with quartodoc locally how the docstrings will appear in the docs?

Thanks @JohnMoutafis, yes it looks as I'd like it locally and we now have all the important classes included in the api ref for the low-level task graph api

[spencerseale]

DAG.submit is not getting included in the doc build because it is defined via submit = submit_udf.

For users, this may be confusing as many of our tutorials reference submit, not submit_udf.

Can we remove this redef and just rename the original submit_udf to submit? @thetorpedodog @JohnMoutafis @ihnorton

[sgillies]

@spencerseale thanks for taking this on! Good docstrings are great for our users.

I've made a suggestion for general comment style. I think that many of these comments are clear from the code and can be omitted.

Many type hints have been added. It would be good to update the title of the PR to reflect that so that reviewers understand the intent as they begin.

[sgillies]

@spencerseale what would you think about using Python comments instead of unassigned strings for this PR?

Suggested change

	"""UUID for Node instance."""
	# UUID for Node instance.

I actually think many of the comments you've added are, while accurate, clear from the code and can be omitted. Less is more. They won't surface in documentation.

[spencerseale]

These """ """ are just meant to materialize the attribute definitions in the docs rather than for someone looking through the code. I definitely agree on not overdoing the comments! My main intent was to get users all information about these classes into the api ref, where currently there is nothing: https://tiledb-inc.github.io/TileDB-Cloud-Py/reference/dag.dag.html

This is what the attributes look like in the api ref now with these:

[sgillies]

@spencerseale Great! I had forgotten that attribute docstrings are a thing. In https://discuss.python.org/t/revisiting-attribute-docstrings/36413 I see that they're pretty widely used and appreciated. I'll amend my review.

[sgillies]

My initial review was made from a place of ignorance regarding attribute docstrings. I'm in favor of them.