[RFC] Do not print the table row if the docstring is empty.

[fenghaolw]

There are often cases that we want to hide some of the attributes from user-facing docs. For example some attributes that are only used for migration or internal debugging purposes, it is confusing to show them in the stardoc.

Ideally there should be some other attributes to indicate this, but for now it seems like it is okay to use empty docstring for this? It is unlikely if anyone want to show a table row with attribute name, type, ... but without any descriptions.

[brandjon]

Hi Hao, thanks for the PR and sorry for the lack of activity. Let me give an update on the state of this repo:

We intend to develop a replacement for stardoc that's built into the Bazel binary. This will avoid skew between a bzl file's true semantics and what the doc tooling thinks the semantics should be. When it's ready, we'll deprecate this repo.

In the meantime, we commit to keeping the essential functionality working, but will not necessarily have the bandwidth to accept enhancements. We'll be making a triage pass over this repo soon and will let you know whether we can merge this PR.

@googlebot scan for cla

[tetromino]

IMHO, parameters without a docstring should be documented: the name and type of parameter may well be self-explanatory.

If we want to hide things from documentation, I would suggest hiding names that start with a non-alphabetic symbol (e.g. underscore).

[tetromino]

Closed per #46 (review)

[fenghaolw]

Can we still use this attribute normally if it starts with underscores? My understanding is that means the attribute is "private". In our cases (inside of Google) it is quite a common to have "public" attribute for migration but really do not want anyone to use. We use scary names like "xxx_for_migration_only_please_do_not_use_without_talking_with_us". Printing this in stardoc is annoying.

[tetromino]

Can we still use this attribute normally if it starts with underscores? My understanding is that means the attribute is "private". In our cases (inside of Google) it is quite a common to have "public" attribute for migration but really do not want anyone to use. We use scary names like "xxx_for_migration_only_please_do_not_use_without_talking_with_us". Printing this in stardoc is annoying.

You're right: attributes that start with _ are private (https://bazel.build/extending/rules#private_attributes_and_implicit_dependencies).

I've written up a feature request in #223 - take a look.