dart-lang / pub-dev

The pub.dev website
https://pub.dev
BSD 3-Clause "New" or "Revised" License
789 stars 146 forks source link

Document entity name/id + parentKey #2959

Open jonasfj opened 5 years ago

jonasfj commented 5 years ago

In our entities we are not good at documenting what the Model.id and Model.parentKey is.

We should go through all entities and make sure this is documented for each Kind. (This is important, as this is how an entity is looked up).

Sometimes we also duplicate properties from the id and parentKey because we can query them without an ancestor key, we should also document all cases where data is duplicated and an invariant must be manually maintained.

jonasfj commented 5 years ago

Asked around, it seems we can do:

  /// Id is...
  @override
  String get id => super.id as String;

  /// Parent key is...
  @override
  db.Key get parentKey;

In short we should add this to all subclasses of db.Model (and db.ExpandoModel).

sigurdm commented 1 month ago

This might still be valuable

Maybe we should document the entire data-model somewhere in a single place, and not spread out over all the model files.