[Super Clipboard] - Document object model, improve naming conventions

[matthew-carroll]

I've been working with super_clipboard for a couple months now and I still don't understand the intentions of the object structure. Things like ClipboardReader vs ClipboardDataReader vs ClipboardData, etc. There are many similarly named things, which have some kind of relationship, but I can't tell what it is. And most them are missing useful Dart Docs to establish usage and context.

Similarly, there are PlatformFormats, FileFormats, ValueFormats, which I assumed were all specializations of the same base class, but I think they all have different base classes. Despite having different base classes, FileFormats and ValueFormats are interspersed under Formats as static constants.

I'm trying to create some fake objects for tests but I'm having a very difficult time faking anything because I can't seem to find a strong seam between any two API surfaces. I fake one thing and end up needing to fake another, then another.

I'm also finding it difficult to understand how these things relate, due to naming within the implementations. Take this method for example, which I'm trying to use to figure out how to fake a plain text reader:

@override
  ReadProgress? getValue<T extends Object>(
    ValueFormat<T> format,
    AsyncValueChanged<T?> onValue, {
    ValueChanged<Object>? onError,
  }) {
    final handleError = onError ??
        (error) {
          Zone.current
              .handleUncaughtError(error, AsyncError.defaultStackTrace(error));
        };
    ReadProgress? progress;
    Future<Object?> onGetData(PlatformFormat format) async {
      final (data, itemProgress) = item.getDataForFormat(format);
      progress ??= itemProgress;
      return await data;
    }

    for (final f in formats) {
      if (format.canDecode(f)) {
        final primaryFormat = format.decodingFormats
            .firstWhere((element) => formats.contains(element));
        format
            .decode(primaryFormat, _PlatformDataProvider(formats, onGetData))
            .then((value) {
          onValue(value);
        }, onError: (e) {
          handleError(e);
        });
        // Decoder must load value immediately, it can't delay loading across
        // await boundary.
        assert(progress != null,
            'decoder didn\'t request value before async boundary.');
        return progress;
      }
    }
    return null;
  }

In this method we see format used to name a PlatformFormat. But format is also used to name a ValueFormat<T>. Then, in addition to format, there's also formats, which is an instance property, which is of type List<PlatformFormat>. Confusingly, the formats of type PlatformFormat are being compared aginst format.decodingFormats, when format is a ValueFormat<T>.

Anyway, this is all very difficult to parse as a reader and I have not yet been able to create enough fake implementation to simulate pasting a single plain text string.