From 6813a397a87dac4e4e8a288bbd79fb75762cfb7f Mon Sep 17 00:00:00 2001 From: Chris Parsons Date: Wed, 27 Feb 2019 15:54:19 -0500 Subject: [PATCH] create a manual documentation-regenerator script and apply it --- WORKSPACE | 2 +- docs/BUILD | 3 +- docs/analysis_test_doc.md | 26 - docs/build_test_doc.md | 11 +- docs/collections_doc.md | 22 +- docs/dicts_doc.md | 11 +- docs/new_sets_doc.md | 810 +++++++++++----------- docs/partial_doc.md | 111 +-- docs/paths_doc.md | 59 +- docs/regenerate_docs.sh | 27 + docs/selects_doc.md | 14 +- docs/shell_doc.md | 12 +- docs/structs_doc.md | 6 +- docs/types_doc.md | 376 +++++------ docs/unittest_doc.md | 1349 +++++++++++++++++-------------------- docs/versions_doc.md | 286 ++++---- 16 files changed, 1511 insertions(+), 1614 deletions(-) create mode 100755 docs/regenerate_docs.sh diff --git a/WORKSPACE b/WORKSPACE index 68b88dc..ad7ff28 100644 --- a/WORKSPACE +++ b/WORKSPACE @@ -12,7 +12,7 @@ load("@bazel_tools//tools/build_defs/repo:git.bzl", "git_repository") git_repository( name = "io_bazel_skydoc", remote = "https://github.com/bazelbuild/skydoc.git", - tag = "0.2.0", + commit = "ac5c106412697ffb9364864070bac796b9bb63d3", ) load("@io_bazel_skydoc//skylark:skylark.bzl", "skydoc_repositories") skydoc_repositories() diff --git a/docs/BUILD b/docs/BUILD index c2c3540..7a8ad84 100644 --- a/docs/BUILD +++ b/docs/BUILD @@ -1,5 +1,4 @@ -load("@io_bazel_skydoc//stardoc:stardoc.bzl", - "stardoc") +load("@io_bazel_skydoc//stardoc:stardoc.bzl", "stardoc") # Note that due to a bug in Bazel 0.22.0, these targets cannot be built without # the --experimental_remap_main_repo flag. diff --git a/docs/analysis_test_doc.md b/docs/analysis_test_doc.md index 472f05e..762a82a 100755 --- a/docs/analysis_test_doc.md +++ b/docs/analysis_test_doc.md @@ -60,29 +60,3 @@ Test rule checking that other targets can be successfully analyzed. -## _analysis_test_impl - -
-_analysis_test_impl(ctx)
-
- -Implementation function for analysis_test. - -### Parameters - - - - - - - - - - - diff --git a/docs/collections_doc.md b/docs/collections_doc.md index 301c3d9..64ffb5e 100755 --- a/docs/collections_doc.md +++ b/docs/collections_doc.md @@ -1,7 +1,7 @@ -## _after_each +## collections.after_each 
-_after_each(separator, iterable)
+collections.after_each(separator, iterable)
Inserts `separator` after each item in `iterable`. @@ -14,7 +14,7 @@ Inserts `separator` after each item in `iterable`. - -
name required. @@ -41,7 +41,7 @@ Typical usage:

targets required. @@ -50,10 +50,13 @@ Typical usage:

kwargs - required. + optional. +

+ The common attributes for tests. +

separator required. @@ -23,7 +23,7 @@ Inserts `separator` after each item in `iterable`.

iterable required. @@ -36,10 +36,10 @@ Inserts `separator` after each item in `iterable`.
-## _before_each +## collections.before_each 
-_before_each(separator, iterable)
+collections.before_each(separator, iterable)
Inserts `separator` before each item in `iterable`. @@ -52,7 +52,7 @@ Inserts `separator` before each item in `iterable`. - separator required. @@ -61,7 +61,7 @@ Inserts `separator` before each item in `iterable`.

- iterable required. @@ -74,10 +74,10 @@ Inserts `separator` before each item in `iterable`. -## _uniq +## collections.uniq 
-_uniq(iterable)
+collections.uniq(iterable)
Returns a list of unique elements in `iterable`. @@ -93,7 +93,7 @@ Requires all the elements to be hashable. - iterable required. diff --git a/docs/dicts_doc.md b/docs/dicts_doc.md index b6ed4da..b266545 100755 --- a/docs/dicts_doc.md +++ b/docs/dicts_doc.md @@ -1,7 +1,7 @@ -## _add +## dicts.add 
-_add(dictionaries)
+dicts.add(dictionaries)
Returns a new `dict` that has all the entries of the given dictionaries. @@ -23,10 +23,13 @@ dictionary, and the sum of a single dictionary is a copy of itself. - dictionaries - required. + optional. +

+ Zero or more dictionaries to be added. +

diff --git a/docs/new_sets_doc.md b/docs/new_sets_doc.md index 59d61af..2a3fb33 100755 --- a/docs/new_sets_doc.md +++ b/docs/new_sets_doc.md @@ -1,375 +1,7 @@ -## _contains +## sets.make 
-_contains(a, e)
-
- -Checks for the existence of an element in a set. - -### Parameters - - - - - - - - - - - - -
e - required. -

- The element to look for. -

-
- - -## _copy - -
-_copy(s)
-
- -Creates a new set from another set. - -### Parameters - - - - - - - - a, b) - - -Returns the elements in `a` that are not in `b`. - -### Parameters - -
- - - - - - - - - - -
b - required. -

- A set, as returned by `sets.make()`. -

-
- - -## _disjoint - -
-_disjoint(a, b)
-
- -Returns whether two sets are disjoint. - -Two sets are disjoint if they have no elements in common. - - -### Parameters - - - - - - - - - - - - -
b - required. -

- A set, as returned by `sets.make()`. -

-
- - -## _get_shorter_and_longer - -
-_get_shorter_and_longer(a, b)
-
- -Returns two sets in the order of shortest and longest. - -### Parameters - - - - - - - - - - - - -
b - required. -

- A set, as returned by `sets.make()`. -

-
- - -## _insert - -
-_insert(s, e)
-
- -Inserts an element into the set. - -Element must be hashable. This mutates the orginal set. - - -### Parameters - - - - - - - - - - - - -
e - required. -

- The element to be inserted. -

-
- - -## _intersection - -
-_intersection(a, b)
-
- -Returns the intersection of two sets. - -### Parameters - - - - - - - - - - - - -
b - required. -

- A set, as returned by `sets.make()`. -

-
- - -## _is_equal - -
-_is_equal(a, b)
-
- -Returns whether two sets are equal. - -### Parameters - - - - - - - - - - - - -
b - required. -

- A set, as returned by `sets.make()`. -

-
- - -## _is_subset - -
-_is_subset(a, b)
-
- -Returns whether `a` is a subset of `b`. - -### Parameters - - - - - - - - - - - - -
b - required. -

- A set, as returned by `sets.make()`. -

-
- - -## _length - -
-_length(s)
-
- -Returns the number of elements in a set. - -### Parameters - - - - - - - - elements) +sets.make(elements) Creates a new set. @@ -385,7 +17,7 @@ All elements must be hashable. -
elements optional. default is None @@ -398,10 +30,398 @@ All elements must be hashable.
-## _remove +## sets.copy 
-_remove(s, e)
+sets.copy(s)
+
+ +Creates a new set from another set. + +### Parameters + + + + + + + + + + + + +
s + required. +

+ A set, as returned by `sets.make()`. +

+
+ + +## sets.to_list + +
+sets.to_list(s)
+
+ +Creates a list from the values in the set. + +### Parameters + + + + + + + + + + + + +
s + required. +

+ A set, as returned by `sets.make()`. +

+
+ + +## sets.insert + +
+sets.insert(s, e)
+
+ +Inserts an element into the set. + +Element must be hashable. This mutates the orginal set. + + +### Parameters + + + + + + + + + + + + + + + + +
s + required. +

+ A set, as returned by `sets.make()`. +

+
e + required. +

+ The element to be inserted. +

+
+ + +## sets.contains + +
+sets.contains(a, e)
+
+ +Checks for the existence of an element in a set. + +### Parameters + + + + + + + + + + + + + + + + +
a + required. +

+ A set, as returned by `sets.make()`. +

+
e + required. +

+ The element to look for. +

+
+ + +## sets.is_equal + +
+sets.is_equal(a, b)
+
+ +Returns whether two sets are equal. + +### Parameters + + + + + + + + + + + + + + + + +
a + required. +

+ A set, as returned by `sets.make()`. +

+
b + required. +

+ A set, as returned by `sets.make()`. +

+
+ + +## sets.is_subset + +
+sets.is_subset(a, b)
+
+ +Returns whether `a` is a subset of `b`. + +### Parameters + + + + + + + + + + + + + + + + +
a + required. +

+ A set, as returned by `sets.make()`. +

+
b + required. +

+ A set, as returned by `sets.make()`. +

+
+ + +## sets.disjoint + +
+sets.disjoint(a, b)
+
+ +Returns whether two sets are disjoint. + +Two sets are disjoint if they have no elements in common. + + +### Parameters + + + + + + + + + + + + + + + + +
a + required. +

+ A set, as returned by `sets.make()`. +

+
b + required. +

+ A set, as returned by `sets.make()`. +

+
+ + +## sets.intersection + +
+sets.intersection(a, b)
+
+ +Returns the intersection of two sets. + +### Parameters + + + + + + + + + + + + + + + + +
a + required. +

+ A set, as returned by `sets.make()`. +

+
b + required. +

+ A set, as returned by `sets.make()`. +

+
+ + +## sets.union + +
+sets.union(args)
+
+ +Returns the union of several sets. + +### Parameters + + + + + + + + + + + + +
args + optional. +

+ An arbitrary number of sets or lists. +

+
+ + +## sets.difference + +
+sets.difference(a, b)
+
+ +Returns the elements in `a` that are not in `b`. + +### Parameters + + + + + + + + + + + + + + + + +
a + required. +

+ A set, as returned by `sets.make()`. +

+
b + required. +

+ A set, as returned by `sets.make()`. +

+
+ + +## sets.length + +
+sets.length(s)
+
+ +Returns the number of elements in a set. + +### Parameters + + + + + + + + + + + + +
s + required. +

+ A set, as returned by `sets.make()`. +

+
+ + +## sets.remove + +
+sets.remove(s, e)
Removes an element from the set. @@ -417,7 +437,7 @@ Element must be hashable. This mutates the orginal set. - s required. @@ -426,7 +446,7 @@ Element must be hashable. This mutates the orginal set.

- e required. @@ -439,10 +459,10 @@ Element must be hashable. This mutates the orginal set. -## _repr +## sets.repr 
-_repr(s)
+sets.repr(s)
Returns a string value representing the set. @@ -455,7 +475,7 @@ Returns a string value representing the set. - s required. @@ -468,13 +488,13 @@ Returns a string value representing the set. -## _to_list +## sets.str 
-_to_list(s)
+sets.str(s)
-Creates a list from the values in the set. +Returns a string value representing the set. ### Parameters @@ -484,7 +504,7 @@ Creates a list from the values in the set. - s required. @@ -497,29 +517,3 @@ Creates a list from the values in the set. -## _union - -
-_union(args)
-
- -Returns the union of several sets. - -### Parameters - - - - - - - - partial, args, kwargs) - - -Calls a partial created using `make`. - -### Parameters - -
- - - - - - - - - - func, args, kwargs) +partial.make(func, args, kwargs) Creates a partial that can be called using `call`. @@ -129,7 +88,7 @@ partial.call(func, x=2) - - - + + +
args - required. -
func required. @@ -138,16 +97,72 @@ partial.call(func, x=2)

args - required. + optional. +

+ Positional arguments to be passed to function. +

kwargs - required. + optional. +

+ Keyword arguments to be passed to function. Note that these can + be overridden at the call sites. +

+
+ + +## partial.call + +
+partial.call(partial, args, kwargs)
+
+ +Calls a partial created using `make`. + +### Parameters + + + + + + + + + + + + + + + + + + diff --git a/docs/paths_doc.md b/docs/paths_doc.md index b626b30..8797c01 100755 --- a/docs/paths_doc.md +++ b/docs/paths_doc.md @@ -1,7 +1,7 @@ -## _basename +## paths.basename 
-_basename(p)
+paths.basename(p)
Returns the basename (i.e., the file portion) of a path. @@ -20,7 +20,7 @@ the final slash). -
partial + required. +

+ The partial to be called. +

+
args + optional. +

+ Additional positional arguments to be appended to the ones given to + make. +

+
kwargs + optional. +

+ Additional keyword arguments to augment and override the ones + given to make. +

p required. @@ -33,10 +33,10 @@ the final slash).
-## _dirname +## paths.dirname 
-_dirname(p)
+paths.dirname(p)
Returns the dirname of a path. @@ -54,7 +54,7 @@ included, unless omitting them would make the dirname empty. - p required. @@ -67,10 +67,10 @@ included, unless omitting them would make the dirname empty. -## _is_absolute +## paths.is_absolute 
-_is_absolute(path)
+paths.is_absolute(path)
Returns `True` if `path` is an absolute path. @@ -83,7 +83,7 @@ Returns `True` if `path` is an absolute path. - path required. @@ -96,10 +96,10 @@ Returns `True` if `path` is an absolute path. -## _join +## paths.join 
-_join(path, others)
+paths.join(path, others)
Joins one or more path components intelligently. @@ -121,7 +121,7 @@ If any component is an absolute path, all previous components are discarded. - path required. @@ -130,20 +130,23 @@ If any component is an absolute path, all previous components are discarded.

- others - required. + optional. +

+ Additional path segments. +

-## _normalize +## paths.normalize 
-_normalize(path)
+paths.normalize(path)
Normalizes a path, eliminating double slashes and other redundant segments. @@ -171,7 +174,7 @@ POSIX platforms; specifically: - path required. @@ -184,10 +187,10 @@ POSIX platforms; specifically: -## _relativize +## paths.relativize 
-_relativize(path, start)
+paths.relativize(path, start)
Returns the portion of `path` that is relative to `start`. @@ -209,7 +212,7 @@ the path both start with the same initial parent references. - path required. @@ -218,7 +221,7 @@ the path both start with the same initial parent references.

- start required. @@ -231,10 +234,10 @@ the path both start with the same initial parent references. -## _replace_extension +## paths.replace_extension 
-_replace_extension(p, new_extension)
+paths.replace_extension(p, new_extension)
Replaces the extension of the file at the end of a path. @@ -250,7 +253,7 @@ If the path has no extension, the new extension is added to it. - p required. @@ -259,7 +262,7 @@ If the path has no extension, the new extension is added to it.

- new_extension required. @@ -273,10 +276,10 @@ If the path has no extension, the new extension is added to it. -## _split_extension +## paths.split_extension 
-_split_extension(p)
+paths.split_extension(p)
Splits the path `p` into a tuple containing the root and extension. @@ -293,7 +296,7 @@ Leading periods on the basename are ignored, so - p required. diff --git a/docs/regenerate_docs.sh b/docs/regenerate_docs.sh new file mode 100755 index 0000000..2ab9a08 --- /dev/null +++ b/docs/regenerate_docs.sh @@ -0,0 +1,27 @@ +#!/bin/bash + +# Copyright 2019 The Bazel Authors. All rights reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# 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. +# +# A script to manually regenerate the documentation contained in the docs/ directory. +# Should be run from the WORKSPACE root. + +set -euo pipefail + +bazel build docs:all --experimental_remap_main_repo + +for filename in bazel-bin/docs/*_gen.md; do + target_filename="$(echo $filename | sed -En "s/bazel-bin\/(.*)_gen.md/\1/p").md" + cp $filename $target_filename +done diff --git a/docs/selects_doc.md b/docs/selects_doc.md index 79cb75e..e26ed4c 100755 --- a/docs/selects_doc.md +++ b/docs/selects_doc.md @@ -1,7 +1,7 @@ -## _with_or +## selects.with_or 
-_with_or(input_dict, no_match_error)
+selects.with_or(input_dict, no_match_error)
Drop-in replacement for `select()` that supports ORed keys. @@ -14,7 +14,7 @@ Drop-in replacement for `select()` that supports ORed keys. - input_dict required. @@ -26,7 +26,7 @@ Drop-in replacement for `select()` that supports ORed keys.

- no_match_error optional. default is "" @@ -52,10 +52,10 @@ Drop-in replacement for `select()` that supports ORed keys. -## _with_or_dict +## selects.with_or_dict 
-_with_or_dict(input_dict)
+selects.with_or_dict(input_dict)
Variation of `with_or` that returns the dict of the `select()`. @@ -72,7 +72,7 @@ macros. - input_dict required. diff --git a/docs/shell_doc.md b/docs/shell_doc.md index 92e11d3..6c655be 100755 --- a/docs/shell_doc.md +++ b/docs/shell_doc.md @@ -1,7 +1,7 @@ -## _array_literal +## shell.array_literal 
-_array_literal(iterable)
+shell.array_literal(iterable)
Creates a string from a sequence that can be used as a shell array. @@ -22,7 +22,7 @@ safety, even if they do not need to be. - iterable required. @@ -36,10 +36,10 @@ safety, even if they do not need to be. -## _quote +## shell.quote 
-_quote(s)
+shell.quote(s)
Quotes the given string for use in a shell command. @@ -56,7 +56,7 @@ shell metacharacters.) - s required. diff --git a/docs/structs_doc.md b/docs/structs_doc.md index abc559b..3b742cb 100755 --- a/docs/structs_doc.md +++ b/docs/structs_doc.md @@ -1,7 +1,7 @@ -## _to_dict +## structs.to_dict 
-_to_dict(s)
+structs.to_dict(s)
Converts a `struct` to a `dict`. @@ -14,7 +14,7 @@ Converts a `struct` to a `dict`. - s required. diff --git a/docs/types_doc.md b/docs/types_doc.md index 8875a65..038ae0a 100755 --- a/docs/types_doc.md +++ b/docs/types_doc.md @@ -1,162 +1,7 @@ -## _a_function +## types.is_list 
-_a_function()
-
- - - - - -## _is_bool - -
-_is_bool(v)
-
- -Returns True if v is an instance of a bool. - -### Parameters - - - - - - - - v) - - -Returns True if v is an instance of a `depset`. - -### Parameters - -
- - - - - - v) - - -Returns True if v is an instance of a dict. - -### Parameters - -
- - - - - - v) - - -Returns True if v is an instance of a function. - -### Parameters - -
- - - - - - v) - - -Returns True if v is an instance of a signed integer. - -### Parameters - -
- - - - - - v) +types.is_list(v) Returns True if v is an instance of a list. @@ -169,7 +14,7 @@ Returns True if v is an instance of a list. -
v required. @@ -182,39 +27,10 @@ Returns True if v is an instance of a list.
-## _is_none +## types.is_string 
-_is_none(v)
-
- -Returns True if v has the type of None. - -### Parameters - - - - - - - - v) +types.is_string(v) Returns True if v is an instance of a string. @@ -227,7 +43,7 @@ Returns True if v is an instance of a string. -
v required. @@ -240,10 +56,97 @@ Returns True if v is an instance of a string.
-## _is_tuple +## types.is_bool 
-_is_tuple(v)
+types.is_bool(v)
+
+ +Returns True if v is an instance of a bool. + +### Parameters + + + + + + + + + + + + +
v + required. +

+ The value whose type should be checked. +

+
+ + +## types.is_none + +
+types.is_none(v)
+
+ +Returns True if v has the type of None. + +### Parameters + + + + + + + + + + + + +
v + required. +

+ The value whose type should be checked. +

+
+ + +## types.is_int + +
+types.is_int(v)
+
+ +Returns True if v is an instance of a signed integer. + +### Parameters + + + + + + + + + + + + +
v + required. +

+ The value whose type should be checked. +

+
+ + +## types.is_tuple + +
+types.is_tuple(v)
Returns True if v is an instance of a tuple. @@ -256,7 +159,94 @@ Returns True if v is an instance of a tuple. - + v + + required. +

+ The value whose type should be checked. +

+ + + + + + +## types.is_dict + +
+types.is_dict(v)
+
+ +Returns True if v is an instance of a dict. + +### Parameters + + + + + + + + + + + + +
v + required. +

+ The value whose type should be checked. +

+
+ + +## types.is_function + +
+types.is_function(v)
+
+ +Returns True if v is an instance of a function. + +### Parameters + + + + + + + + + + + + +
v + required. +

+ The value whose type should be checked. +

+
+ + +## types.is_depset + +
+types.is_depset(v)
+
+ +Returns True if v is an instance of a `depset`. + +### Parameters + + + + + + + + - - -
v required. diff --git a/docs/unittest_doc.md b/docs/unittest_doc.md index 8b65765..2256d12 100755 --- a/docs/unittest_doc.md +++ b/docs/unittest_doc.md @@ -52,654 +52,10 @@ unittest_toolchain(name, -## _ActionInfo +## analysistest.make 
-_ActionInfo(actions)
-
- - - -### Fields - - - - - - - - - - - - -
actions -

(Undocumented)

-
- - - -## _UnittestToolchainInfo - -
-_UnittestToolchainInfo(file_ext, success_templ, failure_templ, join_on)
-
- -Execution platform information for rules in the bazel_skylib repository. - -### Fields - - - - - - - - - - - - - - - - - - - - - - - - -
file_ext -

(Undocumented)

-
success_templ -

(Undocumented)

-
failure_templ -

(Undocumented)

-
join_on -

(Undocumented)

-
- - -## _action_retrieving_aspect_impl - -
-_action_retrieving_aspect_impl(target, ctx)
-
- - - -### Parameters - - - - - - - - - - - - -
ctx - required. -
- - -## _assert_equals - -
-_assert_equals(env, expected, actual, msg)
-
- -Asserts that the given `expected` and `actual` values are equal. - -### Parameters - - - - - - - - - - - - - - - - -
expected - required. -

- The expected value of some computation. -

-
msg - optional. default is None -

- An optional message that will be printed that describes the failure. - If omitted, a default will be used. -

-
- - -## _assert_false - -
-_assert_false(env, condition, msg)
-
- -Asserts that the given `condition` is false. - -### Parameters - - - - - - - - - - - - -

- An optional message that will be printed that describes the failure. - If omitted, a default will be used. -

- - - -
condition - required. -

- A value that will be evaluated in a Boolean context. -

-
- - -## _assert_new_set_equals - -
-_assert_new_set_equals(env, expected, actual, msg)
-
- -Asserts that the given `expected` and `actual` sets are equal. - -### Parameters - - - - - - - - - - - - - - - - -
expected - required. -

- The expected set resulting from some computation. -

-
msg - optional. default is None -

- An optional message that will be printed that describes the failure. - If omitted, a default will be used. -

-
- - -## _assert_set_equals - -
-_assert_set_equals(env, expected, actual, msg)
-
- -Asserts that the given `expected` and `actual` sets are equal. - -### Parameters - - - - - - - - - - - - - - - - -
expected - required. -

- The expected set resulting from some computation. -

-
msg - optional. default is None -

- An optional message that will be printed that describes the failure. - If omitted, a default will be used. -

-
- - -## _assert_true - -
-_assert_true(env, condition, msg)
-
- -Asserts that the given `condition` is true. - -### Parameters - - - - - - - - - - - - -

- An optional message that will be printed that describes the failure. - If omitted, a default will be used. -

- - - -
condition - required. -

- A value that will be evaluated in a Boolean context. -

-
- - -## _begin - -
-_begin(ctx)
-
- -Begins a unit test. - -This should be the first function called in a unit test implementation -function. It initializes a "test environment" that is used to collect -assertion failures so that they can be reported and logged at the end of the -test. - - -### Parameters - - - - - - - - env) - - -Ends a unit test and logs the results. - -This must be called and returned at the end of a unit test implementation function so -that the results are reported. - - -### Parameters - -
- - - - - - env) - - -Ends an analysis test and logs the results. - -This must be called and returned at the end of an analysis test implementation function so -that the results are reported. - - -### Parameters - -
- - - - - - env, expected_failure_msg) - - -Asserts that the target under test has failed with a given error message. - -This requires that the analysis test is created with `analysistest.make()` and -`expect_failures = True` is specified. - - -### Parameters - -
- - - - - - - - - - -
expected_failure_msg - optional. default is "" -

- The error message to expect as a result of analysis failures. -

-
- - -## _fail - -
-_fail(env, msg)
-
- -Unconditionally causes the current test to fail. - -### Parameters - - - - - - - - - - - - -
msg - required. -

- The message to log describing the failure. -

-
- - -## _impl_function_name - -
-_impl_function_name(impl)
-
- -Derives the name of the given rule implementation function. - -This can be used for better test feedback. - -### Parameters - - - - - - - - impl, attrs) - - -Creates a unit test rule from its implementation function. - -Each unit test is defined in an implementation function that must then be -associated with a rule so that a target can be built. This function handles -the boilerplate to create and return a test rule and captures the -implementation function's name so that it can be printed in test feedback. - -The optional `attrs` argument can be used to define dependencies for this -test, in order to form unit tests of rules. - -An example of a unit test: - -``` -def _your_test(ctx): - env = unittest.begin(ctx) - - # Assert statements go here - - return unittest.end(env) - -your_test = unittest.make(_your_test) -``` - -Recall that names of test rules must end in `_test`. - - -### Parameters - -
- - - - - - - - - - -
attrs - optional. default is None -

- An optional dictionary to supplement the attrs passed to the - unit test's `rule()` constructor. -

-
- - -## _make_analysis_test - -
-_make_analysis_test(impl, expect_failure, config_settings)
+analysistest.make(impl, expect_failure, config_settings)
Creates an analysis test rule from its implementation function. @@ -736,7 +92,7 @@ Recall that names of test rules must end in `_test`.
impl required. @@ -745,7 +101,7 @@ Recall that names of test rules must end in `_test`.

expect_failure optional. default is False @@ -755,7 +111,7 @@ Recall that names of test rules must end in `_test`.

config_settings optional. default is {} @@ -771,10 +127,557 @@ Recall that names of test rules must end in `_test`.
-## _suite +## analysistest.begin 
-_suite(name, test_rules)
+analysistest.begin(ctx)
+
+ +Begins a unit test. + +This should be the first function called in a unit test implementation +function. It initializes a "test environment" that is used to collect +assertion failures so that they can be reported and logged at the end of the +test. + + +### Parameters + + + + + + + + + + + + +
ctx + required. +

+ The Skylark context. Pass the implementation function's `ctx` argument + in verbatim. +

+
+ + +## analysistest.end + +
+analysistest.end(env)
+
+ +Ends an analysis test and logs the results. + +This must be called and returned at the end of an analysis test implementation function so +that the results are reported. + + +### Parameters + + + + + + + + + + + + +
env + required. +

+ The test environment returned by `analysistest.begin`. +

+
+ + +## analysistest.fail + +
+analysistest.fail(env, msg)
+
+ +Unconditionally causes the current test to fail. + +### Parameters + + + + + + + + + + + + + + + + +
env + required. +

+ The test environment returned by `unittest.begin`. +

+
msg + required. +

+ The message to log describing the failure. +

+
+ + +## analysistest.target_actions + +
+analysistest.target_actions(env)
+
+ +Returns a list of actions registered by the target under test. + +### Parameters + + + + + + + + + + + + +
env + required. +

+ The test environment returned by `analysistest.begin`. +

+
+ + +## analysistest.target_under_test + +
+analysistest.target_under_test(env)
+
+ +Returns the target under test. + +### Parameters + + + + + + + + + + + + +
env + required. +

+ The test environment returned by `analysistest.begin`. +

+
+ + +## asserts.expect_failure + +
+asserts.expect_failure(env, expected_failure_msg)
+
+ +Asserts that the target under test has failed with a given error message. + +This requires that the analysis test is created with `analysistest.make()` and +`expect_failures = True` is specified. + + +### Parameters + + + + + + + + + + + + + + + + +
env + required. +

+ The test environment returned by `analysistest.begin`. +

+
expected_failure_msg + optional. default is "" +

+ The error message to expect as a result of analysis failures. +

+
+ + +## asserts.equals + +
+asserts.equals(env, expected, actual, msg)
+
+ +Asserts that the given `expected` and `actual` values are equal. + +### Parameters + + + + + + + + + + + + + + + + + + + + + + + + +
env + required. +

+ The test environment returned by `unittest.begin`. +

+
expected + required. +

+ The expected value of some computation. +

+
actual + required. +

+ The actual value returned by some computation. +

+
msg + optional. default is None +

+ An optional message that will be printed that describes the failure. + If omitted, a default will be used. +

+
+ + +## asserts.false + +
+asserts.false(env, condition, msg)
+
+ +Asserts that the given `condition` is false. + +### Parameters + + + + + + + + + + + + + + + + + + + + +
env + required. +

+ The test environment returned by `unittest.begin`. +

+
condition + required. +

+ A value that will be evaluated in a Boolean context. +

+
msg + optional. default is "Expected condition to be false, but was true." +

+ An optional message that will be printed that describes the failure. + If omitted, a default will be used. +

+
+ + +## asserts.set_equals + +
+asserts.set_equals(env, expected, actual, msg)
+
+ +Asserts that the given `expected` and `actual` sets are equal. + +### Parameters + + + + + + + + + + + + + + + + + + + + + + + + +
env + required. +

+ The test environment returned by `unittest.begin`. +

+
expected + required. +

+ The expected set resulting from some computation. +

+
actual + required. +

+ The actual set returned by some computation. +

+
msg + optional. default is None +

+ An optional message that will be printed that describes the failure. + If omitted, a default will be used. +

+
+ + +## asserts.new_set_equals + +
+asserts.new_set_equals(env, expected, actual, msg)
+
+ +Asserts that the given `expected` and `actual` sets are equal. + +### Parameters + + + + + + + + + + + + + + + + + + + + + + + + +
env + required. +

+ The test environment returned by `unittest.begin`. +

+
expected + required. +

+ The expected set resulting from some computation. +

+
actual + required. +

+ The actual set returned by some computation. +

+
msg + optional. default is None +

+ An optional message that will be printed that describes the failure. + If omitted, a default will be used. +

+
+ + +## asserts.true + +
+asserts.true(env, condition, msg)
+
+ +Asserts that the given `condition` is true. + +### Parameters + + + + + + + + + + + + + + + + + + + + +
env + required. +

+ The test environment returned by `unittest.begin`. +

+
condition + required. +

+ A value that will be evaluated in a Boolean context. +

+
msg + optional. default is "Expected condition to be true, but was false." +

+ An optional message that will be printed that describes the failure. + If omitted, a default will be used. +

+
+ + +## register_unittest_toolchains + +
+register_unittest_toolchains()
+
+ +Registers the toolchains for unittest users. + + + +## unittest.make + +
+unittest.make(impl, attrs)
+
+ +Creates a unit test rule from its implementation function. + +Each unit test is defined in an implementation function that must then be +associated with a rule so that a target can be built. This function handles +the boilerplate to create and return a test rule and captures the +implementation function's name so that it can be printed in test feedback. + +The optional `attrs` argument can be used to define dependencies for this +test, in order to form unit tests of rules. + +An example of a unit test: + +``` +def _your_test(ctx): + env = unittest.begin(ctx) + + # Assert statements go here + + return unittest.end(env) + +your_test = unittest.make(_your_test) +``` + +Recall that names of test rules must end in `_test`. + + +### Parameters + + + + + + + + + + + + + + + + +
impl + required. +

+ The implementation function of the unit test. +

+
attrs + optional. default is None +

+ An optional dictionary to supplement the attrs passed to the + unit test's `rule()` constructor. +

+
+ + +## unittest.suite + +
+unittest.suite(name, test_rules)
Defines a `test_suite` target that contains multiple tests. @@ -824,7 +727,7 @@ name each target. - name required. @@ -834,38 +737,12 @@ name each target.

- test_rules - required. - - - - - - -## _target_actions - -
-_target_actions(env)
-
- -Returns a list of actions registered by the target under test. - -### Parameters - - - - - - - - env) +unittest.begin(ctx) -Returns the target under test. - -### Parameters - -
- - - - - - ctx) - +Begins a unit test. +This should be the first function called in a unit test implementation +function. It initializes a "test environment" that is used to collect +assertion failures so that they can be reported and logged at the end of the +test. ### Parameters @@ -918,23 +772,88 @@ _unittest_toolchain_impl(ctx) -
ctx required. +

+ The Skylark context. Pass the implementation function's `ctx` argument + in verbatim. +

-## register_unittest_toolchains +## unittest.end 
-register_unittest_toolchains()
+unittest.end(env)
-Registers the toolchains for unittest users. +Ends a unit test and logs the results. + +This must be called and returned at the end of a unit test implementation function so +that the results are reported. +### Parameters + + + + + + + + + + + + +
env + required. +

+ The test environment returned by `unittest.begin`. +

+
+ + +## unittest.fail + +
+unittest.fail(env, msg)
+
+ +Unconditionally causes the current test to fail. + +### Parameters + + + + + + + + + + + + + + + + +
env + required. +

+ The test environment returned by `unittest.begin`. +

+
msg + required. +

+ The message to log describing the failure. +

+
+ diff --git a/docs/versions_doc.md b/docs/versions_doc.md index 7e9bc21..d94076c 100755 --- a/docs/versions_doc.md +++ b/docs/versions_doc.md @@ -1,170 +1,17 @@ -## _check_bazel_version +## versions.get 
-_check_bazel_version(minimum_bazel_version, maximum_bazel_version, bazel_version)
-
- -Check that the version of Bazel is valid within the specified range. - -### Parameters - - - - - - - - - - - - bazel_version) - - -Extracts the semantic version number from a version string - -### Parameters - -
maximum_bazel_version - optional. default is None -

- maximum version of Bazel expected -

-
- - - - - - - - - -
- - -## _get_bazel_version - -
-_get_bazel_version()
+versions.get()
Returns the current Bazel version -## _is_at_least +## versions.parse 
-_is_at_least(threshold, version)
-
- -Check that a version is higher or equals to a threshold. - -### Parameters - - - - - - - - - - - - -
version - required. -

- the version string to be compared to the threshold -

-
- - -## _is_at_most - -
-_is_at_most(threshold, version)
-
- -Check that a version is lower or equals to a threshold. - -### Parameters - - - - - - - - - - - - -
version - required. -

- the version string to be compared to the threshold -

-
- - -## _parse_bazel_version - -
-_parse_bazel_version(bazel_version)
+versions.parse(bazel_version)
Parses a version string into a 3-tuple of ints @@ -180,7 +27,7 @@ int tuples can be compared directly using binary operators (<, >). - bazel_version required. @@ -193,3 +40,126 @@ int tuples can be compared directly using binary operators (<, >). +## versions.check + +
+versions.check(minimum_bazel_version, maximum_bazel_version, bazel_version)
+
+ +Check that the version of Bazel is valid within the specified range. + +### Parameters + + + + + + + + + + + + + + + + + + + + +
minimum_bazel_version + required. +

+ minimum version of Bazel expected +

+
maximum_bazel_version + optional. default is None +

+ maximum version of Bazel expected +

+
bazel_version + optional. default is None +

+ the version of Bazel to check. Used for testing, defaults to native.bazel_version +

+
+ + +## versions.is_at_most + +
+versions.is_at_most(threshold, version)
+
+ +Check that a version is lower or equals to a threshold. + +### Parameters + + + + + + + + + + + + + + + + +
threshold + required. +

+ the maximum version string +

+
version + required. +

+ the version string to be compared to the threshold +

+
+ + +## versions.is_at_least + +
+versions.is_at_least(threshold, version)
+
+ +Check that a version is higher or equals to a threshold. + +### Parameters + + + + + + + + + + + + + + + + +
threshold + required. +

+ the minimum version string +

+
version + required. +

+ the version string to be compared to the threshold +

+
+ +