dartdoc should allow file-level attributes

[timsneath]

This file provides Dart constants that map onto Win32 constants. There are thousands of these, and there's no reason for me to document them. So I want to /// @nodoc them.

The only way to do that is on a constant-by-constant basis, for example:
https://github.com/timsneath/win32/blob/3e568f0e4fe2deaba3b92c2cdc0d2bb04b739f0b/lib/src/constants.dart#L1715-L1725

Aside from the redundancy and extra work, this ruins the flow of the file and makes it hard to see which constants are grouped together. I'd love a way to annotate this as a file-level nodoc so I could put all these together.

[srawlins]

Hi @timsneath thanks for the report. Is the goal to reduce the number of undocumented elements, or to not expose any elements in a file in Dartdoc? If you don't want them exposed in dartdoc, then removing the export should do the trick.

[srawlins]

According to this doc it looks like you can mark the library directive with /// @nodoc.

[timsneath]

Is the goal to reduce the number of undocumented elements, or to not expose any elements in a file in Dartdoc?

The latter: since otherwise the thousands of constants otherwise pollute the documentation and slow it down hugely. For example, compare the page and sidebar of:
https://pub.dev/documentation/win32/1.4.0/win32/win32-library.html (an old version without @nodoc annotations)
with:
https://pub.dev/documentation/win32/1.6.7/win32/win32-library.html (a more recent version of the documentation).

Unfortunately, these options don't work, as far as I can tell:

• Marking the whole library as non-documented: since I do want the rest of the library to be documented!
• Removing the export, since consuming applications will use these constants.

The constants themselves are essentially self-documenting in the code, and they would be even more self-documenting if I could group them without every other line being a /// @nodoc annotation :)

[srawlins]

Ah I see. You want to mark most of a file as @nodoc? And then things which do have doc comments would be documented? I'm not sure how we'd make a mechanism for that. I'd have to think about that.

For now, the constants which shouldn't be seen in documentation could be moved to a separate file, lib/src/constants2.dart, which is exported from lib/src/constants.dart. Then lib/src/constants2.dart can be marked @nodoc at the library level.

[timsneath]

You want to mark most of a file as @Nodoc? And then things which do have doc comments would be documented?

Not quite: I want the whole constants.dart file to be marked as undocumented.

For now, the constants which shouldn't be seen in documentation could be moved to a separate file, lib/src/constants2.dart, which is exported from lib/src/constants.dart. Then lib/src/constants2.dart can be marked @Nodoc at the library level.

I tried to do this -- but I may have misunderstood your instructions. I created a separate constants2.dart file in its own library, and exported it from constants.dart. However, dartdoc still generates documentation for all 1899 constants. I assume the @nodoc annotation isn't taken into consideration because the contents of the file are exported again.

You can see the results in this branch, in which I've also added the doc/api folder:
https://github.com/timsneath/win32/blob/dartdoc/lib/src/constants.dart

[jcollins-g]

At first glance this sounds like something that should go in dartdoc_options.yaml; tag the file, and have dartdoc pretend any item in the file has a @nodoc tag (possibly, excluding anything that has a (newly defined) @doc tag).

[timsneath]

Hey Janice! Thank you -- yes, that would work well for me. 

In my scenario, I have about 3000 constants (and growing) that really don't need documentation (the name is self-documenting), and having to prefix each of them with @Nodoc bloats the file unnecessarily.