Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

include visible libraries not directly under "lib/", but ignore lib/src #18554

Closed
sigmundch opened this issue Apr 30, 2014 · 11 comments
Closed

include visible libraries not directly under "lib/", but ignore lib/src #18554

sigmundch opened this issue Apr 30, 2014 · 11 comments
Labels
area-pkg Used for miscellaneous pkg/ packages not associated with specific area- teams. P1 A high priority bug; for example, a single project is unusable or has many test failures
Milestone
1.7

Comments

@sigmundch
Copy link
Member

The Dart doc viewer should also include libraries that are public, but not directly under "lib/".

Consider for example the smoke package:
https://code.google.com/p/dart/source/browse/branches/bleeding_edge/dart/pkg/smoke/

It contains the following structure:
 lib/
   |- codegen/
   | |- generator.dart
   | '- recorder.dart
   |
   |- src/
   | '- ...
   |
   |- mirrors.dart
   |- smoke.dart
   |- static.dart
   '- static_debug.dart

Everything outside of 'src/' is part of the public API of this package and is intended to be discoverable (including lib/codegen/...), but we only include docs for the libraries directly under lib:
https://api.dartlang.org/apidocs/channels/stable/dartdoc-viewer/smoke/smoke
@kevmoo
Copy link
Member

kevmoo commented Apr 30, 2014

Sounds reasonable

Removed Area-DartDocViewer label.
Added Area-Pkg, Pkg-DocGen labels.

@efortuna
Copy link
Contributor

efortuna commented May 8, 2014

Currently, as a workaround, if you have other entry points, you can also add them by specifying their paths. For example:

dart pkg/docgen/bin/docgen.dart path/to/first/entryPoint.dart path/to/other/entryPoint.dart and the generated documentation will include both of these.

Removed Priority-Unassigned label.
Added Priority-Low label.

@sethladd
Copy link
Contributor

How could a service like dartdocs.org know what the entry points are?

@alan-knight
Copy link
Contributor

If it can't, how would it expect docgen to know?

@sethladd
Copy link
Contributor

I'm wondering if there's a convention that dartdocs.org could follow and make good guesses? e.g. are there ways to determine entry points?

Maybe we just need a task runner :)

@alan-knight
Copy link
Contributor

Well the suggestion in the bug is that all libraries under lib except in lib/src should be considered to be public and should be documented. That's not unreasonable, but if we did it we might suddenly discover packages that weren't expecting that. +rnystrom +nweiz, is there a rule about this?

cc @munificent.
cc @nex3.

@nex3
Copy link
Member

nex3 commented Sep 11, 2014

Those libraries are intended to be visible. Only lib/src is private.

@sethladd
Copy link
Contributor

Tweaked title and bumped priority.

Removed Priority-Low label.
Added Priority-Medium label.
Changed the title to: "include visible libraries not directly under "lib/", but ignore lib/src".

@kevmoo
Copy link
Member

kevmoo commented Sep 13, 2014

https://codereview.chromium.org/571713002/

Added this to the 1.7 milestone.
Removed Priority-Medium label.
Added Priority-High, Started labels.

@kevmoo
Copy link
Member

kevmoo commented Sep 13, 2014

cc @alan-knight.

@kevmoo
Copy link
Member

kevmoo commented Sep 15, 2014

Fixed r40246

Added Fixed label.

@sigmundch sigmundch added Type-Defect P1 A high priority bug; for example, a single project is unusable or has many test failures area-pkg Used for miscellaneous pkg/ packages not associated with specific area- teams. labels Sep 15, 2014
@sigmundch sigmundch added this to the 1.7 milestone Sep 15, 2014
This issue was closed.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
area-pkg Used for miscellaneous pkg/ packages not associated with specific area- teams. P1 A high priority bug; for example, a single project is unusable or has many test failures
Projects
None yet
Milestone
1.7
Development

No branches or pull requests
6 participants
@nex3 @sethladd @kevmoo @sigmundch @efortuna @alan-knight