'Create Library Packages' page doesn't describe `library` and `part`

[jamesderlin]

Page URL: https://www.dartlang.org/guides/libraries/create-library-packages Page source: https://github.com/dart-lang/site-www/tree/master/src/_guides/libraries/create-library-packages.md

Description: https://www.dartlang.org/guides/language/language-tour#implementing-libraries has:

See Create Library Packages for advice on how to implement a library package, including:

• How to organize library source code.
• How to use the export directive.
• When to use the part directive.
• When to use the library directive

However, the linked "Create Library Packages" page doesn't explain the library or part directives at all. It only has notes such as:

Note: When the library directive isn’t specified, a unique tag is generated for each library based on its path and filename. Therefore, we suggest that you omit the library directive from your code unless you plan to generate library-level documentation.

Note: You may have heard of the part directive, which allows you to split a library into multiple Dart files. We recommend that you avoid using part and create mini libraries instead.

Note: To include any library-level documentation in the generated docs, you must specify the library directive. See issue 1082.

None of these explain what library and part do nor provide any examples for how to use them.

While their usage might be discouraged, they're still part of the language, and it would be nice to document somewhere what they are and what they do.

[jamesderlin]

I'll also add that a lot of Dart documentation (e.g. the "Libraries and visibility" section of the Language Tour talks about "libraries" and mentions that identifiers with a leading _ are private to the library, but it doesn't explain what a library is (other than "Every Dart app is a library", but that raises more questions). Is a library normally a single .dart file? The directory?

[srawlins]

Every Dart app is a library

is perhaps the most confusing and misleading sentence in all of our docs.

[devvercer]

I cannot find documentation anywhere about what the library name is used for. The library is imported using its file name (not the library name). It looks like it is used for resolving deferred imports. What else? This should be documented!

[morrica]

This is indeed difficult to figure out. Based on the information a google search can provide it seems that the library directive is intended to make the following private access work, but it doesn't.

File base_thing.dart:

library thing;

import 'my_imports';

class BaseThing {
  void _doAThing() {}
}

File thing.dart:

library thing;

import 'my_other_imports';
import 'base_thing.dart';

class Thing extends BaseThing {
  void doMyThing() {
    _doAThing();
  }
}

The solution seems to be to use part, part of directives, but that doesn't really work if I have a Thing2 that also wants access to BaseThing.