Document abstract fields

[petro-i]

Page URL

https://dart.dev/language/keywords.html

Page source

https://github.com/dart-lang/site-www/tree/main/src/language/keywords.md

Describe the problem

Missing reference to abstract fields. They are introduced for abstract classes for null-safety.

[parlough]

Thanks so much for filing this issue! I'm going to adjust the goal of it a bit, as we don't actually document abstract fields at all in the language docs. Once we do that, we can cross-link there from the table.

@MaryaBelanger I never noticed we didn't document this in the language docs, only in Understanding null safety. I'm not sure where we should document it now though, now that abstract classes are documented later as part of class modifiers.

Maybe after https://dart.dev/language/methods#getters-and-setters and before https://dart.dev/language/methods#abstract-methods?

[eernstg]

It is mentioned here: https://github.com/dart-lang/language/blob/main/accepted/2.12/abstract-external-fields/feature-specification.md.

Like other accepted feature specifications, this will be integrated into the language specification. We just haven't done that yet.

[MaryaBelanger]

Maybe after https://dart.dev/language/methods#getters-and-setters and before https://dart.dev/language/methods#abstract-methods?

That makes sense because of their relation to getters and setters. I'm a little concerned about having "abstract fields" under methods (should I be?). Could it also make sense directly on the Classes page, maybe after Instance variables?

[parlough]

Since abstract fields are essentially a syntax sugar for an abstract getter + setter (if not final), I don't see any problem.

My main concern with documenting it under the current class page is that we haven't introduced abstract classes at that point yet.

No matter what we do here, I'm starting to think we maybe should pull the abstract class docs out of class modifiers and as its own page.

[MaryaBelanger]

No matter what we do here, I'm starting to think we maybe should pull the abstract class docs out of class modifiers and as its own page.

I was thinking the same. Ok, so:

• "Abstract classes" stand alone page under "Classes"
  • (still point to it from "Class modifiers")
• "Abstract fields" under "Getters and setters"
  • Remove it from "Understanding null safety"? (maintain the section with a pointer)
  • Or leave some of the less practical / more story-of-development info there
• And of course the original request to add another "abstract" entry to the keywords table
  • "abstract (class)" and "abstract (field)"
  • Not mentioned in the issue, but would that mean we need to also add "abstract (method)"? Seems like a lot
    • One idea is we could have the keywords table point to an "abstract" glossary entry that says something like:
      "Abstract is the general idea that <summarize high level shared abstract traits between classes, fields, and methods>. It can refer to: classes, fields, or methods (link on each)"

[parlough]

That works for me :)

I was however considering a new page that could document the concept of abstract as a whole: abstract classes, abstract methods, abstract fields, etc. This all applies to sealed classes as well since they are implicitly abstract.

Otherwise it seems like it will become a big web of a lot of pages to understand abstract classes.

This would potentially be after "Extend a class" since that gives some of the context necessary to understand when an abstract class would be helpful.

With this route, the keyword could just link to one page :)

[MaryaBelanger]

With this route, the keyword could just link to one page :)

Yes! I like that idea best. So the move then is to create the new page and more or less paste the three existing sections of contents (classes, methods, and fields) to that page. There will probably be cleaning up to make it more cohesive but I don't imagine too much. And something like the overarching glossary definition I mentioned could be the page intro. Then just point to the new page from the old sections.

Lmk if you want to take this one! (though it seems straight forward enough for me to manage 😅 up to you!)

[parlough]

I'm going to be focusing on the DartPad stuff for a while, so if this is something you'd like to prioritize, feel free. Otherwise, someone can get to it when we get to it :)

It should be mostly copy pasting as you said.