Docs update and format

Author: srikrsna-buf

WORKSPACE

@@ -11,7 +11,7 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-# 
+#
 workspace(name = "rules_buf")
 
 load("//buf:repositories.bzl", "rules_buf_dependencies", "rules_buf_toolchains")

buf/internal/breaking.bzl

@@ -18,39 +18,9 @@ load("@rules_proto//proto:defs.bzl", "ProtoInfo")
 load(":plugin.bzl", "protoc_plugin_test")
 
 _DOC = """
-This checks protocol buffers for breaking changes using `buf breaking`. 
-For an overview of breaking change detection using buf please refer: https://docs.buf.build/breaking/overview.
+`buf_breaking_test` is a test rule that checks one or more `proto_library` targets for breaking changes. 
 
-**NOTE**: 
-In order to truly check breaking changes this rule should be used to check all `proto_library` targets that come under a [buf module](https://docs.buf.build/bsr/overview#module). 
-Using unique test targets for each `proto_library` target checks each `proto_library` target in isolation. 
-Checking targets/packages in isolation has the obvious caveat of not being able to detect when an entire package/target is removed/moved.
-
-**Gazelle**
-
-The [gazelle extension](/gazelle/buf/README.md) can be used generate this rule. It supports generating once for buf module and also at a bazel package level.
-
-**Example**
-
-This rule depends on `proto_library` rule.
-
-```starlark
-load("@rules_buf//buf:defs.bzl", "buf_breaking_test")
-load("@rules_proto//proto:defs.bzl", "proto_library")
-
-proto_library(
-    name = "foo_proto",
-    srcs = ["foo.proto"],
-)
-
-buf_breaking_test(
-    name = "foo_proto_breaking",
-    # Image file to check against. Please refer to https://docs.buf.build/reference/images.
-    against = "@build_buf_foo_foo//:file",
-    targets = [":foo_proto"],
-    config = ":buf.yaml",
-)
-```
+For more info please refer to the [`buf_breaking_test` section](https://docs.buf.build/build-systems/bazel#buf-lint-test) of the docs.
 """
 
 _TOOLCHAIN = str(Label("//tools/protoc-gen-buf-breaking:toolchain_type"))

buf/internal/lint.bzl

@@ -18,33 +18,9 @@ load("@rules_proto//proto:defs.bzl", "ProtoInfo")
 load(":plugin.bzl", "protoc_plugin_test")
 
 _DOC = """
-This lints protocol buffers using `buf lint`.
-For an overview of linting using buf please refer: https://docs.buf.build/lint/overview.
+`buf_lint_test` is a test rule that lints one or more `proto_library` targets.
 
-**Gazelle**
-
-The [gazelle extension](/gazelle/buf/README.md) can be used generate this rule.
-
-**Example**
-
-This rule depends on `proto_library` rule.
-
-```starlark
-load("@rules_buf//buf:defs.bzl", "buf_lint_test")
-load("@rules_proto//proto:defs.bzl", "proto_library")
-
-proto_library(
-    name = "foo_proto",
-    srcs = ["pet.proto"],
-    deps = ["@go_googleapis//google/type:datetime_proto"],
-)
-
-buf_lint_test(
-    name = "foo_proto_lint",    
-    targets = [":foo_proto"],
-    config = "buf.yaml",
-)
-```
+For more info please refer to the [`buf_lint_test` section](https://docs.buf.build/build-systems/bazel#buf-lint-test) of the docs.
 """
 
 _TOOLCHAIN = str(Label("//tools/protoc-gen-buf-lint:toolchain_type"))
@@ -56,7 +32,7 @@ def _buf_lint_test_impl(ctx):
     })
     files_to_include = []
     if ctx.file.config != None:
-        files_to_include.append(ctx.file.config) 
+        files_to_include.append(ctx.file.config)
     return protoc_plugin_test(ctx, proto_infos, ctx.executable._protoc, ctx.toolchains[_TOOLCHAIN].cli, config, files_to_include)
 
 buf_lint_test = rule(

buf/internal/repo.bzl

@@ -17,7 +17,10 @@
 load("@bazel_tools//tools/build_defs/repo:utils.bzl", "update_attrs")
 
 _DOC = """
-The `buf_dependencies` rule downloads and generates `proto_library` targets for buf modules hosted on the BSR.
+`buf_dependencies` is a [repository rule](https://bazel.build/rules/repository_rules) that downloads one or more modules from the [BSR](https://docs.buf.build/bsr/introduction) and generates build files using Gazelle.
+[Setup Gazelle](https://github.com/bazelbuild/bazel-gazelle#setup) to use this rule.
+
+For more info please refer to the [`buf_dependencies` section](https://docs.buf.build/build-systems/bazel#buf-dependencies) of the docs.
 """
 
 def _executable_extension(ctx):