Documentation for properties is painfully verbose

[jacob314]

Documentation for properties is painfully verbose
As Dart already allows fields and properties to be used interchangeably in interfaces and classes, we should always represent properties as fields where practical in the DartDoc. This issue is high priority because documentation for all properties is shown twice for all properties with documentation from MDN making the docs much harder to read.

For example:

http://api.dartlang.org/html/Element.html

String get contentEditable()
Gets/sets whether or not the element is editable.
from MDN

void set contentEditable(String value)
Gets/sets whether or not the element is editable.
from MDN

The documentation should instead read:

String contentEditable
Gets/sets whether or not the element is editable.
from MDN

For read only fields the documentation should read:

final String tagName;
The name of the tag for the given element.

Instead of
String get tagName()
The name of the tag for the given element.

For the very rare cases where getters and setters have different types we can fall back to the existing documentation style.
If the getter and setter have different documentation (never occurs for HTML) we can either display the documentation for the getter followed by the setter in the same block or fall back to the existing style of listing the getter and setter separately.

[anders-sandholm]

Added Area-DartDoc label.

[munificent]

Because of Dart's syntax for getters and setters, this is actually hard to do well, but we may be able to work around that with some heuristics and conventions.

---

Added this to the M1 milestone.

[munificent]

Issue #2798 has been merged into this issue.

---

cc @sethladd.

[jmesserly]

FWIW: I generally have been only documenting one of the getter/setter pair (usually the getter), and assuming that DartDoc will eventually do something smart here :)

[DartBot]

This comment was originally written by [email protected]

---

I'm looking at (http://api.dartlang.org/docs/continuous/dart_io/Process.html), and the documentation for a getter looks like:

    OutputStream stdin()
    Returns an output stream to the process stdin.

    Throws an UnsupportedOperationException if the process is non-interactive.

stdin() looks like a method, not a getter. In fact, I didn't believe it actually was a getter until I saw the code.

[sethladd]

Adding John Messerly for an FYI for new API app.

---

cc @jmesserly.

[DartBot]

This comment was originally written by [email protected]

---

Looks like the HTML library has worked around this by exposing the getter/setter pair as a field on the interface, e.g. Element.dartdoc:
  /** @­domName HTMLElement.contentEditable */
  String contentEditable;

JJ, I think you're reporting a different issue where getters were apparently just being documented wrong? Current rendering is "OutputStream get stdin()" -- clear enough that this is a getter?

I would still like if dartdoc did some clever magic itself to render getters/setters as fields, but I think the current state will get us past M1. Bumping to M2, please pull it back if you object.

---

Removed this from the M1 milestone.
Added this to the M2 milestone.

[jmesserly]

@eub: there was a bug that was preventing "get" from being displayed, looks like it has been fixed.

But we still need to display these as fields. The syntax for using properties does not match the documentation, and this has come up repeatedly as a cause of user confusion in hackathons and new user studies.

[munificent]

Removed the owner.

[dgrove]

Set owner to @jacob314.

[munificent]

I seem to remember Johhni doing something related to this recently. There may be another bug that covers this.

[dgrove]

Removed this from the M2 milestone.
Added this to the M3 milestone.

[anders-sandholm]

Removed this from the M3 milestone.
Added this to the M4 milestone.

[DartBot]

This comment was originally written by [email protected]

---

Is this still an issue?

If not, will be fixed after issue #8857

---

Added NeedsInfo label.
Marked this as being blocked by #8857.

[jmesserly]

It looks fixed to me:
http://api.dartlang.org/docs/releases/latest/dart_html/Element.html#contentEditable

---

Added Fixed label.