Augmenting declarations cannot occur outside parts, right?

[eernstg]

[Update: At this time, May 2024, there are no library augmentation files. We will use parts to do this job. Changed the title accordingly.]

Thanks to @sgrekhov for bringing up this topic. I might have missed it, but I do not think the augmentation library specification specifies that

It is an error for an augmenting declaration to occur in any library which is not an augmentation library.

That is, a library that contains a library augment ... directive can have augment declarations, others can't.

[eernstg]

@jakemac53, @munificent, do you agree?

[jakemac53]

This is the current spec yes - but there have been discussions about allowing them anywhere so it could change.

[lrhn]

I agree that that's what's specified.
I disagree that it's necessary, and would like it changed: #3576. (Probably part of the discussion Jake refers to.)

You can have an empty "main" library file with a single "augment import "real_library.dart";` declaration, then declare all your stuff in that library augmentation file, and have both your main declarations and augmentation declarations in the same file.

If you can do that, we might as well allow declaring augmentations in the main library file too.

You can argue that you shouldn't need to have declarations and augmentations on top of those declarations in the same library, but I'm not absolutely certain there aren't things you can do with class+augment class that you can't do (or do as easily) with a single class.

Maybe someone just likes to do:

class Pomegranate { 
  // all the base stuff
}
// All the Iterable stuff here.
augment class Pomegranate with Iterable<Seed> {
  Iterator<Seed> get iterator => ...
}
// All the comparable stuff here.
augment class Pomegranate implements Comparable<Pomegranate> {
  int compareTo(Pomegranate other) => weight.compareTo(other.weight);
  static int compare(Pomegranate p1, Pomegranate p2) => p1.compareTo(p2);
}

Who are we to disallow that (or force them to have an extra spurious file to achieve it), if there is no technical reason for it. </soapbox>

[eernstg]

So every library can contain augment declarations?

[eernstg]

I'd recommend allowing augmentations in a library as well as in a library augmentation, but each augmenting declaration should apply to an original declaration in the same library. (This is in line with the rule that every augmentation should apply to the original declaration, or to an augmenting declaration which occurs in the parent chain of library augmentations, or in the main library. That is, "you can only augment your parents, which includes yourself". ;-)

@dart-lang/language-team, WDYT?

[jakemac53]

SGTM, I think this is in line with the recent in person discussions on this.

It does make me sad that you can't augment a declaration produced by a macro, given that macro augmentations always come last, but I don't see a reasonable way around that.

[lrhn]

Agree. If macro introspection can only see entire, fully augmented declarations, there is no way we can also have augmentations that occur after macros.

[davidmorgan]

I believe this is implemented in #3848