Update templates for macro returns and deprecations

[segiddins]

Closes #58

[thomasvl]

@c-parsons can you take a look

The buildifier failure seem to be on the test files; so and existing issue?

[segiddins]

The buildkite link 404s for me -- is there any way for me to see what the failures are so I can fix them?

[thomasvl]

test/testdata/misc_apis_test/input.bzl:20: provider-params: Calls to 'provider' should provide a documentation:\n  provider("description", fields = [...])
test/testdata/provider_basic_test/input.bzl:2: provider-params: Calls to 'provider' should provide a list of fields and a documentation:\n  provider("description", fields = [...])
test/testdata/providers_for_attributes_test/dep.bzl:3: provider-params: Calls to 'provider' should provide a list of fields:\n  provider("description", fields = [...])
test/testdata/providers_for_attributes_test/input.bzl:8: provider-params: Calls to 'provider' should provide a documentation:\n  provider("description", fields = [...])
test/testdata/providers_for_attributes_test/input.bzl:15: provider-params: Calls to 'provider' should provide a list of fields and a documentation:\n  provider("description", fields = [...])

[segiddins]

Hmm so # buildifier: disable=provider-params doesn't seem to allow disabling that check for some reason?

[brandjon]

Hi Samuel, thanks for the PR. Just an update on 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

[keith]

We intend to develop a replacement for stardoc that's built into the Bazel binary

any timeline on that?

[brandjon]

Design doc in Q1, most likely implementation in Q2.

Note that this work isn't just for stardoc's sake. It's part of a broader effort to better specify Bazel's loading phase. Removing the current stardoc implementation will also simplify Bazel's code (no more starlarkbuildapi/ interfaces).

[brandjon]

I should clarify, the replacement we're talking about concerns how documentation info is actually extracted from bzl files. It does not necessarily mean this specific repo will be deprecated. That is, the templating/formatting logic might remain here even after the redesign.

The important point is we will be prioritizing developing the new architecture over feature requests in this repo.

[tetromino]

@segiddins, would you mind rebasing this after the jar updates and buildifier-ing in https://github.com/bazelbuild/stardoc/pull/97?

[segiddins]

Rebased, my apologies for the delay!

[tetromino]

@brandjon - would you mind taking a look and ack-ing this?