Siklos/libgit2dart
1
0
Fork 0
mirror of https://github.com/SkinnyMind/libgit2dart.git synced 2025-05-05 12:49:08 -04:00
Code Issues Projects Releases Wiki Activity

docs: improve api documentation

Browse source
This commit is contained in:
Aleksey Kulikov 2021-10-22 14:41:15 +03:00
parent 199dce111a
commit a24070c44c
32 changed files with 1008 additions and 518 deletions
Download patch file Download diff file Expand all files Collapse all files

71
lib/src/commit.dart
View file

@ -8,12 +8,12 @@ class Commit {
/// Initializes a new instance of [Commit] class from provided pointer to
/// commit object in memory.
///
/// Should be freed to release allocated memory.
/// **IMPORTANT**: Should be freed to release allocated memory.
Commit(this._commitPointer);
/// Lookups commit object for provided [oid] in a [repo]sitory.
/// Lookups commit object for provided [oid] in the [repo]sitory.
///
/// Should be freed to release allocated memory.
/// **IMPORTANT**: Should be freed to release allocated memory.
Commit.lookup({required Repository repo, required Oid oid}) {
_commitPointer = bindings.lookup(
repoPointer: repo.pointer,
@ -26,30 +26,49 @@ class Commit {
/// Pointer to memory address for allocated commit object.
Pointer<git_commit> get pointer => _commitPointer;
/// Creates new commit in the repository.
/// Creates new commit in the [repo]sitory.
///
/// [updateRef] is name of the reference that will be updated to point to this commit.
/// [repo] is the repository where to store the commit.
///
/// [updateRef] is the name of the reference that will be updated to point to this commit.
/// If the reference is not direct, it will be resolved to a direct reference. Use "HEAD"
/// to update the HEAD of the current branch and make it point to this commit. If the
/// reference doesn't exist yet, it will be created. If it does exist, the first parent
/// must be the tip of this branch.
///
/// [author] is the signature with author and author time of commit.
///
/// [committer] is the signature with committer and commit time of commit.
///
/// [messageEncoding] is the encoding for the message in the commit, represented with
/// a standard encoding name. E.g. "UTF-8". If null, no encoding header is written and
/// UTF-8 is assumed.
///
/// [message] is the full message for this commit.
///
/// [tree] is an instance of a [Tree] object that will be used as the tree for the commit.
/// This tree object must also be owned by the given [repo].
///
/// [parents] is a list of [Commit] objects that will be used as the parents for this commit.
/// This array may be empty if parent count is 0 (root commit). All the given commits must
/// be owned by the [repo].
///
/// Throws a [LibGit2Error] if error occured.
static Oid create({
required Repository repo,
required String message,
String? updateRef,
required Signature author,
required Signature commiter,
required Signature committer,
String? messageEncoding,
required String message,
required Tree tree,
required List<Commit> parents,
String? updateRef,
String? messageEncoding,
}) {
return Oid(bindings.create(
repoPointer: repo.pointer,
updateRef: updateRef,
authorPointer: author.pointer,
committerPointer: commiter.pointer,
committerPointer: committer.pointer,
messageEncoding: messageEncoding,
message: message,
treePointer: tree.pointer,
@ -68,6 +87,12 @@ class Commit {
/// the tip of the branch and then rewrite the following commits to reach a ref, pass
/// this as null and update the rest of the commit chain and ref separately.
///
/// Unlike [create], the [author], [committer], [message], [messageEncoding], and
/// [tree] arguments can be null in which case this will use the values from the original
/// [commit].
///
/// All arguments have the same meanings as in [create].
///
/// Throws a [LibGit2Error] if error occured.
static Oid amend({
required Repository repo,
@ -91,28 +116,29 @@ class Commit {
));
}
/// Returns the encoding for the message of a commit, as a string
/// representing a standard encoding name.
/// Wncoding for the message of a commit, as a string representing a standard
/// encoding name.
String get messageEncoding => bindings.messageEncoding(_commitPointer);
/// Returns the full message of a commit.
/// Full message of a commit.
///
/// The returned message will be slightly prettified by removing any potential leading newlines.
/// The returned message will be slightly prettified by removing any potential
/// leading newlines.
String get message => bindings.message(_commitPointer);
/// Returns the [Oid] of a commit.
/// [Oid] of a commit.
Oid get oid => Oid(bindings.id(_commitPointer));
/// Returns the commit time (i.e. committer time) of a commit.
/// Commit time (i.e. committer time) of a commit.
int get time => bindings.time(_commitPointer);
/// Returns the committer of a commit.
/// Committer of a commit.
Signature get committer => Signature(bindings.committer(_commitPointer));
/// Returns the author of a commit.
/// Author of a commit.
Signature get author => Signature(bindings.author(_commitPointer));
/// Returns list of parent commits [Oid]s.
/// List of parent commits [Oid]s.
List<Oid> get parents {
var parents = <Oid>[];
final parentCount = bindings.parentCount(_commitPointer);
@ -128,7 +154,7 @@ class Commit {
return parents;
}
/// Get the tree pointed to by a commit.
/// Tree pointed to by a commit.
Tree get tree {
return Tree(tree_bindings.lookup(
repoPointer: bindings.owner(_commitPointer),
@ -152,8 +178,9 @@ class Commit {
///
/// Note: for internal use.
class AnnotatedCommit {
/// Lookups an annotated commit from the given commit [oid]. The resulting annotated commit
/// must be freed to release allocated memory.
/// Lookups an annotated commit from the given commit [oid].
///
/// **IMPORTANT**: Should be freed to release allocated memory.
///
/// Throws a [LibGit2Error] if error occured.
AnnotatedCommit.lookup({required Repository repo, required Oid oid}) {