Unusually large output for a smallish library

[isoos]

Original report: dart-lang/pub-dev#5122
Package: https://pub.dev/packages/opengl version 0.5.0

It looks like https://gitlab.com/ext/dart-opengl/-/blob/master/lib/src/opengl_header.dart is a rather large file, and generating a separate documentation file for all of its fields hits pub.dev's 2GB limit. Maybe dartdoc could decide to only generate an overview file if the library has more than X fields/methods/classes (X > 10k)?

[jcollins-g]

It'd probably be easier, and more feasible internally, to have a dartdoc directive for the library that says "generate overview only". That way users could control this themselves. Thoughts?

[isoos]

After a brief discussion, this seems to be a not that great idea, as it breaks permalinks if they reference a member file. Maybe a better solution would be to separate the side menu that links to all the other members and embed it as a separate file into a member page.

[jcollins-g]

@isoos By "break permalinks", you mean that if someone adds this directive without updating their permanent links, they will break? I think that's probably OK, unless there's a piece I'm not understanding here? We can, by default, continue to have the present behavior, just allow for something different if the user knows they have a ginormous header-file style library.

[isoos]

by "break permalinks", you mean that if someone adds this directive without updating their permanent links, they will break?

That, and also: if another package depends on it, the API symbol references generated in this new package's documentation may point to files that are no longer generated.

[jcollins-g]

by "break permalinks", you mean that if someone adds this directive without updating their permanent links, they will break?

That, and also: if another package depends on it, the API symbol references generated in this new package's documentation may point to files that are no longer generated.

Ah, OK, that was what using a dartdoc directive was designed to address. If the code and/or dartdoc_options.yaml has this as an option, other invocations of dartdoc will know of the difference in how the pages will be generated and can generate API symbol references accordingly.

The main issue there would be that you would have to rerun dartdoc with the new version to update the API docs for existing packages.

[jcollins-g]

Oh, never mind, I think I see what you mean now. Any time someone alters this flag, we'd have to rebuild the world. That would not be a good idea.

Demoting to P3 unless I can noodle up a better way to handle this.