Dart-Docs for grouping of constants.

[terrylucas]

I've many groups of constants and would like to see similar constants grouped and sorted together. Some argument sake I'm using [+group name] as the Dart-doc for grouping/sorting. Notice that a constant can be used in multiple groups (see NORMAL). For example:

class Font {
  /** [+Font style][+Font variant][+Font weight] [NORMAL] default. /
  static final String NORMAL = "normal";
  /* [+Font style] [ITALIC] right-slant font (if it exist). /
  static final String ITALIC = "italic";
  /* [+Font style] [OBLIQUE] generate right-slant font. */
  static final String OBLIQUE = "oblique";

  /** [+Font variant] [SMALL_CAPS] lowercase characters in smaller cap font. */
  static final String SMALL_CAPS = "small-caps";

  /** [+Font weight] [NORMAL_BOLD] bold thickness. */
  static final int BOLD_WEIGHT = 700;

  /** [+Generic family] sans-serif (w/o serifs). /
  static final String SANS_SERIF_GENERIC = "sans-serif";
  /* [+Generic family] serif font. /
  static final String SERIF_GENERIC = "serif";
  /* [+Generic family] fixed-width font. /
  static final String MONOSPACE_GENERIC = "monospace";
  /* [+Generic family] emulate handwriting font. /
  static final String CURSIVE_GENERIC = "cursive";
  /* [+Generic family] decorative font. */
  static final String FANTASY_GENERIC = "fantasy";
}

Would like output to be:

Font Style
  ITALIC right-slant font (if it exist).
  NORMAL default.
  OBLIQUE generate right-slant font.

Font Variant
  NORMAL default.
  SMALL_CAPS lowercase characters in smaller cap font.

Font Weight
  NORMAL default.
  BOLD_WEIGHT bold thickness.

Generic family
  CURSIVE_GENERIC emulate handwriting font.
  FANTASY_GENERIC decorative font.
  MONOSPACE_GENERIC fixed-width font.
  SANS_SERIF_GENERIC sans-serif font.
  SERIF_GENERIC serif font.

Also, would be nice to somehow bind a parameter name in a method to the group for example:

class Font {
  num weight;
  String style;

  /**
   * [weight [+Font weight]] [style [+Font style]] [family [+Generic family][+Serif family][+Sans-serif family]]
  Font([this.weight, this.style, this.family]);
}

So that weight, style and family are bookmarks to the appropriate definition.

[DartBot]

This comment was originally written by [email protected]

---

Related "problem": sometimes, methods in an interface are logically divided into some groups (before you start thinking "then split the interface into two or more", take a look at List), and alphabetical order in generated doc makes it harder to understand. Explicit grouping is a good idea that would solve this issue too.

[dgrove]

Added Triaged label.

[anders-sandholm]

Added Area-DartDoc label.

[munificent]

I definitely think we should do something here, but I'm not sure if this is the ideal design.

---

Added this to the Later milestone.

[dgrove]

to fix in the next generation dartdoc viewer.

---

cc @jmesserly.
Set owner to @jacob314.

[DartBot]

This comment was originally written by [email protected]

---

Marked this as being blocked by #8857.

[DartBot]

This comment was originally written by @seaneagan

---

I think keeping it more simple, with declarations only belonging to a single group would be enough. Then you just need a beginning and end delimiter around the group of declarations.

Possible design: use the "part" directive, allow inline parts:

/// ### Foo constants
/// These constants represent foo
part 'foo_constants.dart';

class {
  /// ### Bar methods
  /// These methods allow you to bar...
  part {
    bar1();
    bar2();
    bar3();
  }
}

[DartBot]

This comment was originally written by @seaneagan

---

the multiple groups could possibly be handled by using the export directive to create separate libraries for each group.

[jacob314]

Set owner to @efortuna.

[efortuna]

cc @alan-knight.
Removed the owner.

[alan-knight]

Removed Type-Defect, Area-DartDoc labels.
Added Type-Enhancement, Area-DartDocNext labels.

[DartBot]

This comment was originally written by @seaneagan

---

Are there any plans for this?

As part of this, it would be nice to also include an option as to whether to order the docs for a particular group in source order instead of alphabetically. For example the logger level docs would be nicer if they were ordered in source order which would correspond to the order specified by the comparison operators in Logger:

http://test.dartdoc-next.appspot.com/#logging/logging.Level

Another option besides comment #­7 above would be using metadata. Could just annotate the first member of the group, in which case each declaration in source order until the next annotated one, or the end of the current block, belongs to that group.

@DOCGroup('Levels', order: DocOrder.SOURCE)
static const Level OFF = const('OFF', 0);
// ...
static const Level SHOUT = const('SHOUT', 1200);
static const Level ALL = const('ALL', 2000);

Or could annotate each member of the group.

const level = const DocGroup('Levels', order: DocOrder.SOURCE);

@Level static const Level OFF = const('OFF', 0);
// ...
@Level static const Level SHOUT = const('SHOUT', 1200);
@Level static const Level ALL = const('ALL', 2000);

which could often be written with just a single annotation

@DOCGroup('Levels', order: DocOrder.SOURCE)
static const Level
    OFF = const('OFF', 0),
    // ...
    SHOUT = const('SHOUT', 1200),
    ALL = const('ALL', 2000);

[alan-knight]

Source code order is bug 12513, but likely not possible with the way we get the information right now (dart2js source mirrors).

Grouping would be good to do but is not yet being worked on.

[alan-knight]

Issue #12677 has been merged into this issue.

[anders-sandholm]

Removed Area-DartDocNext label.
Added Area-DartDoc label.

[DartBot]

This comment was originally written by [email protected]

---

I would love to see grouping with dartdoc, like the grouping mechanisms in Doxygen (@­defgroup, @­addtogroup, @­name, @­{ ... @­} grouping.

For my purpose, I have a lot of global functions that have grouped relationships with each other, and would like to group the related functions in the documentation.

[kevmoo]

Removed Area-DartDoc label.
Added Pkg-DartDoc label.

[kevmoo]

Added Area-Pkg label.

[kevmoo]

Removed Pkg-DartDoc label.
Added Pkg-DocGen label.