Consider an option to limit size of code samples

[jonasfj]

If documentation pages are too large it gives a poor user experience.

Maybe, we should have an option to limit size of code snippets / implementation / descriptions ?

Perhaps if the "implementation" is significantly long there should be a limit on it. I could see us having similar limits on descriptions too, doesn't have to small limits. Just sanity limits would be nice to have :D

It would be fine to make "..." at the end of the description of an identifier exceeds something like 500kb.

Maybe omit implementation longer than 80kb, or something?

Example

From: https://pub.dev/documentation/isitaword/latest/words/words.html

[srawlins]

This is an interesting suggestion, but I haven't seen any other examples of 500kb dartdoc pages. Since the example you show is all in the implementation, I'm 100% in favor of limiting the implementation text to something sane like... 10kb? I think at some point we just want to make this a link out to GitHub/whereever instead of inline impl.

[jonasfj]

@srawlins

I haven't seen any other examples of 500kb dartdoc pages

Have you seen: https://pub.dev/documentation/google_fonts/latest/google_fonts/GoogleFonts-class.html

It's about 251kb gzipped, 9.4mb uncompressed! :rofl: And it's not just degenerate code snippets, but you can argue that it's probably a lot of generated code. I don't know if compilation times would improve if this library was split in multiple files.

Or: https://pub.dev/documentation/sdl2/latest/sdl2/sdl2-library.html It's 135kb compressed, 2.3mb uncompressed.

Maybe, we should consider a condensed form for pages with more than 500 identifiers (or 1000 identifiers, just some reasonable limit). Like maybe, at a certain number of identifiers, we switch to a form where there is a section for classes and a bullet list with a link for each classes, and similar with a section for method, constants, exceptions, enums, etc. So we omit summary and possibly even signatures (or maybe just links from signatures). Just an idea.

[jonasfj]

I'm 100% in favor of limiting the implementation text to something sane like... 10kb?

Yeah, that's seems perfectly sane. An implementation larger than 10kb is probably too big for anyone to read anyways. We could also set the limit at 30kb no problem.

I think at some point we just want to make this a link out to GitHub/whereever instead of inline impl.

I agree, we should do code-browsing on pub.dev some day, ideally with cross linking and such.