dartdoc is confusing on getters/setters

[jmesserly]

e.g. http://api.dartlang.org/io/ServerSocket.html
This was causing confusion at the hackathon, especially because of the inline function type

The syntax matches how they are declared, but not how they're used.
It'd be nice to either show the usage form too, or choose a neutral form that looks more like a field.

[jmesserly]

(not sure the best area -- but most bugs seem to be in Area-Site.)

---

Removed Component-Docs label.
Added Area-Site label.

[sethladd]

Yes, this came up in the hackathon, very confusing to people. Unclear how to use setter.

void set onConnection(void callback(Socket socket))

People wanted to do this:

onConnection((Socket socket) => doStuff());

Instead they need to do this:

onConnection = (Socket socket) => doStuff();

What about formatting the docs like:

void set onConnection = void callback(Socket socket)

with a doc comment like
/**
 * Assign a callback to be run for every new connection. For example:
 * serverSocket.onConnection = (Socket socket) => doStuff(socket);
 */

---

cc @munificent.

[munificent]

void set onConnection = void callback(Socket socket)

This is confusing to me because it looks like it's trying to be Dart syntax, but isn't. It's neither how setters are declared or invoked.

I've talked about this with Jacob a bit. The ideal solution is that we will document getters and setters exactly as if they were fields. To a consumer of the API, there is no difference between fields and getters/setters, so there shouldn't be in the docs.

The problem is that the Dart language currently allows you to do things with getters and setters that you can't do with fields. For example, the getter and setter can have different types. Or you can have a setter with no getter.

Given that getters and setters each have their own docs (because they are defined separately), it also isn't clear which dartdoc would be used if we joined them into a single field-like entry in the generated docs.

The last we talked about it, the plan was to document getters/setters like fields when possible (i.e. when the types match and there is a getter) and then fallback to something like the current system when it isn't. But I don't know when I'll get around to doing this.

What I'd really like is a better syntax for defining getters and setters in the language so that these problems are avoided, but I don't think that's a priority for Lars and co.

[sethladd]

Good point, it's not exactly Dart syntax. I think treating like fields is a good compromise, as the use case for getters/setters is "you can refactor from fields".

[sethladd]

Removed Area-Site label.
Added Area-DartDoc label.

[munificent]

Added Duplicate label.
Marked as being merged into #1509.