feat: in-manifest and in-lib documentation of feature toggles (#329)

Sebastian Thiel committed 4 years ago

Commit aa3795d1 parent c7dff9e4 files · +26 −28Browse files

Unified · Split

4 files

Cargo.lock +1 −0
cargo-features.md +1 −21
gitoxide-core/Cargo.toml +19 −7
gitoxide-core/src/lib.rs +5 −0

@@ -1759,6 +1759,7 @@ dependencies = [ · 1758 unmodified lines
1759	1759	"async-trait",
1760	1760	"blocking",
1761	1761	"bytesize",
	1762	+ "document-features",
1762	1763	"fs-err",
1763	1764	"futures-io",
1764	1765	"futures-lite",

cargo-features.md+1−21

@@ -50,27 +50,7 @@ There are convenience features, which combine common choices of the above in · 49 unmodified lines
50	50
51	51	### gitoxide-core
52	52
53		−The library powering the command-line interface.
54		−
55		−* organize
56		− * provides the 'organize' command
57		− * Includes `jwalk` to find repositories quickly in order to move into a directory structure automatically.
58		− * provides the 'find' command
59		− * discover all git repositories within a directory. Particularly useful with [skim][skim].
60		−* estimate-hours
61		− * Derive the amount of time invested akin to [git-hours].
62		−* _mutually exclusive_
63		− - if both are set, _blocking-client_ will take precedence.
64		− - blocking-client
65		− - If set, the client used to connect to git servers will use a blocking API. It supports more transports and is what most would want.
66		− - async-client
67		− - The client to connect to git servers will be async, while supporting only the 'git' transport itself. It's the most limited and can be seen as example
68		− on how to use custom transports for custom servers.
69		−* local-time-support
70		− - Functions dealing with time may include the local timezone offset, not just UTC with the offset being zero.
71		−
72		−[skim]: https://github.com/lotabout/skim
73		−[git-hours]: https://github.com/kimmobrunfeldt/git-hours
	53	+Documented in [its documentation](https://docs.rs/gitoxide-core).
74	54
75	55	### git-pack
76	56

gitoxide-core/Cargo.toml+19−7

@@ -13,18 +13,28 @@ test = false · 12 unmodified lines
13	13
14	14	[features]
15	15	default = []
16		−## Data structures implement `serde::Serialize` and `serde::Deserialize`.
17		−serde1 = ["git-commitgraph/serde1", "git-repository/serde1", "serde_json", "serde"]
18	16
19		−# async or blocking tooling
	17	+#! ### Tools
	18	+## Discover all git repositories within a directory. Particularly useful with [skim](https://github.com/lotabout/skim).
	19	+organize = ["git-url", "jwalk"]
	20	+## Derive the amount of time invested into a git repository akin to [git-hours](https://github.com/kimmobrunfeldt/git-hours).
	21	+estimate-hours = ["itertools", "rayon", "fs-err"]
	22	+
	23	+#! ### Mutually Exclusive Networking
	24	+#! If both are set, _blocking-client_ will take precedence, allowing `--all-features` to be used.
	25	+
	26	+## If set, the client used to connect to git servers will use a blocking API. It supports more transports and is what most would want.
20	27	blocking-client = ["git-repository/blocking-network-client"]
	28	+## The client to connect to git servers will be async, while supporting only the 'git' transport itself.
	29	+## It's the most limited and can be seen as example on how to use custom transports for custom servers.
21	30	async-client = ["git-repository/async-network-client", "async-trait", "futures-io", "async-net", "async-io", "futures-lite", "blocking"]
22	31
	32	+#! ### Other
	33	+## Data structures implement `serde::Serialize` and `serde::Deserialize`.
	34	+serde1 = ["git-commitgraph/serde1", "git-repository/serde1", "serde_json", "serde"]
	35	+## Functions dealing with time may include the local timezone offset, not just UTC with the offset being zero.
23	36	local-time-support = ["git-repository/local-time-support"]
24	37
25		−# tools
26		−organize = ["git-url", "jwalk"]
27		−estimate-hours = ["itertools", "rayon", "fs-err"]
28	38
29	39	[dependencies]
30	40	# deselect everything else (like "performance") as this should be controllable by the parent application.
@@ -56,5 +66,7 @@ rayon = { version = "1.5.0", optional = true } · 25 unmodified lines
56	66	itertools = { version = "0.10.1", optional = true }
57	67	fs-err = { version = "2.6.0", optional = true }
58	68
	69	+document-features = { version = "0.1.0", optional = true }
	70	+
59	71	[package.metadata.docs.rs]
60		−features = ["blocking-client", "organize", "estimate-hours", "serde1"]
	72	+features = ["document-features", "blocking-client", "organize", "estimate-hours", "serde1"]

gitoxide-core/src/lib.rs+5−0

@@ -1,3 +1,8 @@
	1	+//! ## Feature Flags
	2	+#![cfg_attr(
	3	+ feature = "document-features",
	4	+ cfg_attr(doc, doc = ::document_features::document_features!())
	5	+)]
1	6	#![forbid(unsafe_code)]
2	7	#![deny(rust_2018_idioms)]
3	8	#![cfg_attr(feature = "async-client", allow(unused))]

feat: in-manifest and in-lib documentation of feature toggles (#329)

Keyboard shortcuts

General

Issues and pull requests

Issues, pull requests and Inbox

Repository code