Do not export web.dart from helpers.dart

[ditman]

It seems convenient, but it makes the following documentation page:

• https://pub.dev/documentation/web/0.4.0/helpers/helpers-library.html

Very hard to tell apart from:

• https://pub.dev/documentation/web/0.4.0/web/web-library.html

(Alternatively, expose a library that exports only the helpers so I can find their documentation, and what's available :))

[devoncarew]

I came here to file this same issue. When using this package, I'd expect to import:

import 'package:web/web.dart';

or possibly:

import 'package:web/web.dart';
import 'package:web/web_helpers.dart';

but not:

import 'package:web/helpers.dart';

I wouldn't think of 'helpers' as the main library in this package.

[ditman]

@devoncarew actually package:web/web_helpers.dart may be a good name for "the package that only exports the helpers and nothing more" :P

[devoncarew]

I took a stab at it in #109 -

[devoncarew]

@srujzs, @kevmoo:

The current setup seems odd to me (web.dart for generated APIs, helpers.dart for manually written convenience members):

• helpers.dart re-exports web.dart, which doubles the API surface area
• people using the helpers would primarily interact w/ this package by importing package:web/helpers.dart, which seems odd

I'm curious if we think that most people using this package will use the helpers? All people using this package? I could see two alternative setups:

• package:web/web.dart (purely generated APIs)
• package:web/web_helpers.dart (hand written convenience code)

This would mean you could use the apis w/ just the first import, but perhaps typical usage would require both imports?

Alternatively, this could be:

• package:web/web.dart (which would export both the generate apis and the hand-written ones)
• package:web/src/web_gen.dart (generated APIs)
• package:web/src/web_helpers.dart (hand written code)

This setup would make sense if we believed most idiomatic use of the package would use the helpers.

Thoughts?

[srujzs]

It makes sense to me to avoid exporting web.dart through the helpers. The helpers are meant to be an add-on, and it doesn't make sense for users to be able to import everything through a file called "helpers". Typical usage will indeed use both though, so maybe that's less ideal. On the other hand, I don't want the helpers to be exported through web.dart as users who don't want to use the helpers shouldn't need to include that code.

If needing both imports is not okay, an alternative is to make helpers.dart web_with_helpers.dart.

[devoncarew]

To paraphrase an off-line discussion:

• we'll move to everything being imported via just package:web/web.dart
• that will export both the generated apis and the manually written helper apis
  • generated apis move to something like package:web/src/core.dart
  • helper apis move to something like package:web/src/helpers.dart
• we don't think we need the generated apis separately available (separate from the helpers), but can always pivot on that based on feedback and real world usage
• we deprecate the current package:web/helpers.dart and remove it for the next major release