Documentation improvements for the List module

[e-kayrakli]

The following are some notes that I took while reviewing the List interface. I think some of them are open to discussion and are related to our general documentation strategy. But here's what I think personally:

• I'd probably put proc size and proc indices closer to the beginning.
• For methods with bunch of overloads, can we
  (1) Implement a generic version that gives a verbose compiler error,
  (2) document that version, listing alternative types that can be passed,
  (3) no-doc actual implementations?
• OOB warnings should probably be in the header and not in every single function's documentation.
• remove documentation should specify what happens if count is larger than the count of elements actually in the list. (I am assuming silently return the actual number that's less than count is returned?)
• I think we are leaning towards not documenting readWriteThis?
• We can also probably not document operators, and instead mention in the header that the list type supports those operators. But it may be just me.

[lydia-duncan]

* OOB warnings should probably be in the header and not in every single function's documentation.

My main worry is that someone will miss the warning if they enter the documentation at a particular method rather than from the start of the module documentation. But having a quick link to a longer warning would also help with that.

* We can also probably not document operators, and instead mention in the header that the `list` type supports those operators. But it may be just me.

Personally, I've found having operator overloads defined explicitly on a type helpful in other languages. Especially when the operator takes the type for one side of a binary operation and another type for the other. It might also be useful to have chpldoc make a separate section for operators, but I think that's dependent on #5946

[lydia-duncan]

I agree with the other line items :)

[e-kayrakli]

My main worry is that someone will miss the warning if they enter the documentation at a particular method rather than from the start of the module documentation. But having a quick link to a longer warning would also help with that.

I think this is a reasonable point. One potential compromise is to have "lighter-weight" warnings, that doesn't take up so much space, or maybe collapsible ones. Arguable that's a lot of effort though.

Personally, I've found having operator overloads defined explicitly on a type helpful in other languages. Especially when the operator takes the type for one side of a binary operation and another type for the other. It might also be useful to have chpldoc make a separate section for operators, but I think that's dependent on #5946

I agree that there should be some documentation, and would think that separate operators section (that we probably render a little differently) would make great sense. And until then we may have to keep what we have.