New Issue: Documentation improvements for the 'List' module

Notifications Issues
1

18111, "e-kayrakli", "Documentation improvements for the 'List' module", "2021-07-26T17:27:21Z"

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.