Revise and somewhat expand Prepare docs#1813
Conversation
This revises the `gix_command::Prepare` documentation, mainly for clarity but also to add some information and cover or explain some cases that were not (or not as fully) covered before. This builds on recent documentation changes, such as those in GitoxideLabs#1800. Less importantly, this also: - Wraps `Prepare` documentation comments to a more consistent width, when doing so improved unrendered readability. - Made a trace message more precise, to avoid obscuring a subtlety about the distinction between what we are looking for and what we are adding, since that might occasionally relate to the reason someone is examining trace messages.
Sebastian Thiel (Byron)
left a comment
Sebastian Thiel (Byron)
left a comment
There was a problem hiding this comment.
Thanks a lot for helping with this! It's probably close to perfect now in terms of documentation.
If there was such a thing, it feels like this crate is approaching maturity even though I keep thinking that allow_*/disallow_* should rather be with_*(bool). Also I thought that there should be no 'double-duty' methods that do two things at once.
Before bringing it to 1.0.0, it might be best to wait until more has been done related to running commands on different platforms and environments, including running hooks on Windows, to see if that entails any changes to the interface itself. (I assume this may also motivate changes to the implementation including currently existing parts of it, but I think that's separate from what you mean, since changes to the implementation would usually be non-breaking as far as the interface is concerned.) |
2 participants
Closes #1799
This revises the
gix_command::Preparedocumentation, mainly for clarity but also to add some information and cover or explain some cases that were not (or not as fully) covered before.This builds on recent documentation changes, such as those in #1800. In so doing, I believe it completes the last remaining task of #1799, among other changes.
Less importantly, this also:
Preparedocumentation comments to a more consistent width, when doing so improved unrendered readability.Although this is in part motivated by the documentation improvements in #1800 and by the goal of further clarifying the meaning of the various methods that are affected there, this does not do anything related to the
\-related concerns presented in #1800 (comment). The changes here are completely independent of that.