Documentation: Organize dartdoc API output

[rickbsgu]

dartdoc lumps all of the classes together without any distinction. Same with functions, constants, etc.

These need to organized under header by type, category, etc.

Not straightforward. Investigating.

[rickbsgu]

I'm making some progress using the 'categories' feature in dartdoc.

By tagging classes with the following (in the prefixing comment):

/// {@category Some Category}
///
class SomeClass {
}

and making some entries in dartdoc_options.yaml along with some commandline options, dartdoc lists the categories in the left sidebar under 'Topics'. Clicking on a category in the 'Topics' list displays the classes tagged with that category.

[rickbsgu]

Here's what I've been able to do, so far. Note the categories may not be correct or complete - this just shows how it works.

https://rickbsgu.github.io/mix/apidoc/

Note the 'Topics' column in the left side bar. You can click on any of those for a list of classes that fall under that 'Topic' (category).

[leoafarias]

@rickbsgu this looks really good! This will make things much easier to navigate.

[rickbsgu]

No longer applicable

Version 2: Instead of 'categories', I've listed the source in multiple libraries.

Location: my fork https://github.com/rickbsgu/mix, branch rickb-docs-2.
Docs output webpage: https://rickbsgu.github.io/mix/apidoc/

---

The overall 'mix' library is still there, it's just excluded from the documentation generation so that it doesn't generate duplicate content. The 'mix' library exports the category libraries rather than the lower level source files.

I ran the tests to make sure this works - it all seems to work just fine.

I think this may be a better way to go rather than by categories by virtue of the fact that everything that is in that library gets documented as part of that library - global functions, constants, extensions, etc. Categories only includes classes (as far as I've been able to tell.)

Note that we can exclude content as we want.

We can also go as fine-grained as we want. For instance, an entire library could be devoted to 'image attributes' which would only list those that make sense for attributes. Similar for text attributes, iconattributes, Decorators, Variants, etc.

Downsides:

• I think we may have to do a bit of source reorganizing to get the libs to reflect categories properly.
• We have to name the separate libraries according to the dart convention - e.g. I'd rather it listed "mixable_widgets" as "Mixable Widgets", but we don't have control over that.
• Don't have control over the ordering of the libraries. I'd like to list the more important ones first. One way to do that would be to prefix the library name - a-<name>, b-<name>, .... Clunky, but it would work.

I don't think any of these are show-stoppers.

[rickbsgu]

Well, after actually using it, I'm less convinced it's useful as it is.

Have to think on it some more.

Update
I've thought about it - gonna do this again and go back to 'topics' approach and restricted input.

[rickbsgu]

Ok, after a bit of a hiatus, I've taken another swing at this. I think this effort works much better.

This is not complete, but it illustrates the approach sufficiently well to determine whether to move forward or no.

My fork and branch: https://github.com/rickbsgu/mix/tree/rickb-docs-4
Resulting docs: https://rickbsgu.github.io/mix/doc/api/

Points:

• Doing a straight up dartdoc invocation on the entire code source makes a mess - it's hard to understand the organization of the package.
• The approach here has been to remove all of the source files by placing them in a nodoc section of the dartdoc_options.yaml file, and then taking them out of the section one by one as a given file is to be documented, tagging the classes, adding links, and any other commenting to be documented as necessary (see below.)
• I've gone back to tagging the classes with categories (these turn up as Topics). Each 'Topic' (category) page allows for explanatory text and lists the classes tagged with that topic at the bottom.
• The class listings are color tagged with their category, as well.
• I've added forward and backward links in appropriate classes to ease navigation between widget and relevant attributes/utilities for that widget.
• The difficulty has been Short Utils. Because they're global, they get dumped in the global space and don't fall under any topic — it's very confusing. They just get mixed in with the classes and other objects. To separate them out (but still document them), the approach taken here has been two-fold:
  • Put the Short Utils files in the nodoc list in the dartdoc_options.yaml file so they don't document.
  • In the respective Utility class, under each static function that sets an attribute, add a canonical comment listing the short util for that function.

Example:

class BoxUtility {
  ...
  /// Short Utils: marginRight, mr
  static BoxAttributes marginRight(double value) {
    return BoxAttributes(margin: EdgeInsetsDto.only(right: value));
  }
  ...
  /// Short Utils: bgColor
  static BoxAttributes backgroundColor(Color color) =>
      BoxAttributes(color: color);
  ...

Now, in the documentation for the BoxUtility class Static Functions list, the output looks like this:

backgroundColor([Color]> >() color) → BoxAttributes
Short Utils: bgColor

marginRight(double value) → BoxAttributes
Short Utils: marginRight, mr

Upsides

• By putting files in the nodoc list, or adding @⁠nodoc tags in the code to remove code elements, the API docs are greatly reduced, noise is greatly reduced, and the user should be able to get to what they want to reference. Forward and backward links between relevant classes helps the navigation for a given widget.
• Listing the Short Utils with their respective static Utility class functions ties them together. This has added benefits, listed below.

Downsides

• The approach is labor-intensive. Category tags have to be added to each class/item you want categorized. nodoc listing has to be maintained in the dartdoc_options.yaml file. Short Utils need to be listed by hand.

Side Benefits

A side benefit of this approach has been that it exposes inconsistencies and omissions.

Aside: For about a day and a half, I was banging my head trying to figure out why the file text_directives.utils.dart wasn't getting picked up by dartdoc. (I even dug into dartdoc's source code trying to figure out what was happening — pretty dense code...).

The issue turned that out the file wasn't included the Mix package's nested exports.dart file.

Some of the Short Codes are inconsistently defined, or missing. For instance, for the BoxUtility.marginHorizontal() function, the corresponding Short Codes are marginHorizontal, marginX, and mx, but for the BoxUtility.paddingHorizontal() function we have paddingHorizontal and px, but no paddingX. Also, we have BoxUtility and TextUtility but TextDirectiveUtils. Some of the static utility functions are defined as arrow functions and some are defined with normal braced function syntax (simple return functions.)

Admittedly these are minor points, but inconsistencies can be glaring to a user — when you're cooking along, it can be jarring to have to check to see if a utility class ends in '...Utils' or '...Utility', or find out that an expected Short Code like paddingX isn't there.

Synopsis

It's not perfect — ideally the Short Codes would be automatically generated in a way that collects them with their corresponding widget & we wouldn't have to do so much manually.

But, the approach has the benefit of keeping the Short Codes with their Utility functions and, the attention required to document them exposes inconsistencies and omissions.

It's a PITA, but I think it's worth it.

PS

I've filed some issues in the dartdoc project:

• Show subCategories in Sidebar as SubTopics dart-lang/dartdoc#2954
• Allow items to be tagged to list of categories, rather than single category dart-lang/dartdoc#2955
• Allow grouping of globals (or other) under 'group' tag dart-lang/dartdoc#2956
• 'category-order' cli flag and 'categoryOrder' in yaml don't order categories dart-lang/dartdoc#2958
• Display category topics on all pages (or add a flag to do so) dart-lang/dartdoc#2959
• Extensions with category tags not showing up on the associated topic page dart-lang/dartdoc#2966

The first two would be useful for items like Directives, which would be a subcategory or additional category to Attributes.

The third would be useful for things like Short Codes and other global constants and function.

The rest are just annoying or bugs.

[leoafarias]

@rickbsgu This looks really good!! I believe there could be some adjustment to the category Mix Object, but I think overall the topics is the way to go!

[rickbsgu]

Ok. I've refactored the decorator classes to be more in line with the rest of the classes, especially with regards to utilities and short utils and how they show up in the documentation.

This shouldn't introduce any breaking changes - all the class names are the same and the Mix exports are the same. I'll be checking this further.

Note: I've run all the tests, some of which use decorator classes - they all pass.

Relevant changes:

• Created the files 'decorator_utils.dart' and 'decorator_short_utils.dart'
• Moved all of the global 'utility' functions in each of the decorator classes into corresponding <decorator>Utility classes in 'decorator_utils.dart' as static member arrow functions.
• Created short utils for all in the file 'decorator_short_utils.dart'.
• Renamed the 'clip_utilities/clip_rrect.dart' file to 'clip_decorator.dart'.
• Removed the 'clip_utilities/clip_utils.dart' file and moved the TriangleClip class into the 'clip_decorator.dart file.
• Converted the rest of the clip 'utility' globals to static ClipDecoratorUtility members the same as the other decorator utilities, along with short codes.

The result is the decorator class definitions are now consistent with the the rest of the attribute definitions, and document consistently.

[rickbsgu]

The folks at dartdoc have been quite responsive - note they've fixed two of the issues listed above (purple checks) which improve the organization of the output, greatly.

[leoafarias]

That is great news!!!

[rickbsgu]

I think we can close this with the pull merge.