refactor: update comments for documentation (#51)

* comments for docs

* update

Author: seokju-na

index.d.ts

@@ -17,9 +17,9 @@ impl Deref for BlobInner {
   }
 }
 
-/// A structure to represent a git [blob][1]
+/// A class to represent a git [blob][1].
 ///
-/// [1]: http://git-scm.com/book/en/Git-Internals-Git-Objects
+/// [1]: https://git-scm.com/book/en/Git-Internals-Git-Objects
 #[napi]
 pub struct Blob {
   pub(crate) inner: BlobInner,
@@ -28,7 +28,7 @@ pub struct Blob {
 #[napi]
 impl Blob {
   #[napi]
-  /// Get the id (SHA1) of a repository blob
+  /// Get the id (SHA1) of a repository blob.
   pub fn id(&self) -> String {
     self.inner.id().to_string()
   }

src/blob.rs

@@ -12,12 +12,12 @@ pub struct CommitOptions {
   pub update_ref: Option<String>,
   /// Signature for author.
   ///
-  /// If not provided, default signature of repository will be used.
+  /// If not provided, the default signature of the repository will be used.
   /// If there is no default signature set for the repository, an error will occur.
   pub author: Option<SignaturePayload>,
   /// Signature for commiter.
   ///
-  /// If not provided, default signature of repository will be used.
+  /// If not provided, the default signature of the repository will be used.
   /// If there is no default signature set for the repository, an error will occur.
   pub committer: Option<SignaturePayload>,
   pub parents: Option<Vec<String>>,
@@ -40,7 +40,7 @@ impl Deref for CommitInner {
 }
 
 #[napi]
-/// A structure to represent a git commit
+/// A class to represent a git commit.
 /// @hideconstructor
 pub struct Commit {
   pub(crate) inner: CommitInner,
@@ -74,7 +74,7 @@ impl Commit {
   /// The returned message will be slightly prettified by removing any
   /// potential leading newlines.
   ///
-  /// Throws error if the message is not valid utf-8
+  /// Throws error if the message is not valid utf-8.
   pub fn message(&self) -> crate::Result<String> {
     let message = std::str::from_utf8(self.inner.message_raw_bytes())?.to_string();
     Ok(message)
@@ -113,10 +113,6 @@ impl Commit {
 
   #[napi]
   /// Get the commit time (i.e. committer time) of a commit.
-  ///
-  /// The first element of the tuple is the time, in seconds, since the epoch.
-  /// The second element is the offset, in minutes, of the time zone of the
-  /// committer's preferred time zone.
   pub fn time(&self) -> crate::Result<DateTime<Utc>> {
     let time = DateTime::from_timestamp(self.inner.time().seconds(), 0).ok_or(crate::Error::InvalidTime)?;
     Ok(time)
@@ -134,7 +130,7 @@ impl Commit {
   }
 
   #[napi]
-  /// Casts this Commit to be usable as an `GitObject`
+  /// Casts this Commit to be usable as an `GitObject`.
   pub fn as_object(&self) -> GitObject {
     let obj = self.inner.as_object().clone();
     GitObject {
@@ -169,9 +165,9 @@ impl Repository {
   }
 
   #[napi]
-  /// Create new commit in the repository
+  /// Create new commit in the repository.
   ///
-  /// If the `update_ref` is not `null`, name of the reference that will be
+  /// If the `updateRef` is not `null`, 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

src/commit.rs

@@ -10,13 +10,13 @@ use std::ops::Deref;
 #[napi]
 #[repr(u32)]
 pub enum DiffFlags {
-  /// File(s) treated as binary data. (1 << 0)
+  /// File(s) treated as binary data.
   Binary = 1,
-  /// File(s) treated as text data. (1 << 1)
+  /// File(s) treated as text data.
   NotBinary = 2,
-  /// `id` value is known correct. (1 << 2)
+  /// `id` value is known correct.
   ValidId = 4,
-  /// File exists at this side of the delta. (1 << 3)
+  /// File exists at this side of the delta.
   Exists = 8,
 }
 
@@ -34,9 +34,9 @@ pub fn diff_flags_contains(source: u32, target: u32) -> bool {
 pub enum DeltaType {
   /// No changes
   Unmodified,
-  /// Entry does not exist in old version
+  /// Entry does not exist in an old version
   Added,
-  /// Entry does not exist in new version
+  /// Entry does not exist in a new version
   Deleted,
   /// Entry content changed between old and new
   Modified,
@@ -93,19 +93,19 @@ impl From<DeltaType> for git2::Delta {
 }
 
 #[napi(string_enum)]
-/// Possible output formats for diff data
+/// Possible output formats for diff data.
 pub enum DiffFormat {
-  /// full git diff (default)
+  /// full `git diff` (default)
   Patch,
   /// just the headers of the patch
   PatchHeader,
-  /// like git diff --raw
+  /// like `git diff --raw`
   Raw,
-  /// like git diff --name-only
+  /// like `git diff --name-only`
   NameOnly,
-  /// like git diff --name-status
+  /// like `git diff --name-status`
   NameStatus,
-  /// git diff as used by git patch-id
+  /// `git diff` as used by `git patch-id`
   PatchId,
 }
 
@@ -137,8 +137,8 @@ pub struct DiffPrintOptions {
 /// The diff object that contains all individual file deltas.
 ///
 /// This is an opaque structure which will be allocated by one of the diff
-/// generator functions on the `Repository` structure (e.g. `diff_tree_to_tree`
-/// or other `diff_*` functions).
+/// generator functions on the `Repository` class (e.g. `diffTreeToTree`
+/// or other `diff*` functions).
 ///
 /// @hideconstructor
 pub struct Diff {
@@ -199,7 +199,7 @@ impl Diff {
 }
 
 #[napi]
-/// Structure describing a hunk of a diff.
+/// A class describing a hunk of a diff.
 ///
 /// @hideconstructor
 pub struct DiffStats {
@@ -228,7 +228,7 @@ impl DiffStats {
 }
 
 #[napi(iterator)]
-/// An iterator over the diffs in a delta
+/// An iterator over the diffs in a delta.
 ///
 /// @hideconstructor
 pub struct Deltas {
@@ -271,7 +271,7 @@ impl DiffDelta {
   }
 
   #[napi]
-  /// Returns the status of this entry
+  /// Returns the status of this entry.
   pub fn status(&self) -> DeltaType {
     self.inner.status().into()
   }
@@ -357,7 +357,7 @@ impl DiffFile {
   #[napi]
   /// Returns the Oid of this item.
   ///
-  /// If this entry represents an absent side of a diff (e.g. the `old_file`
+  /// If this entry represents an absent side of a diff (e.g. the `oldFile`
   /// of a `Added` delta), then the oid returned will be zeroes.
   pub fn id(&self) -> String {
     self.inner.id().to_string()
@@ -371,7 +371,7 @@ impl DiffFile {
   }
 
   #[napi]
-  /// Returns the size of this entry, in bytes
+  /// Returns the size of this entry, in bytes.
   pub fn size(&self) -> u64 {
     self.inner.size()
   }
@@ -402,7 +402,7 @@ impl DiffFile {
 }
 
 #[napi(object)]
-/// Structure describing options about how the diff should be executed.
+/// Describing options about how the diff should be executed.
 pub struct DiffOptions {
   /// Flag indicating whether the sides of the diff will be reversed.
   pub reverse: Option<bool>,
@@ -643,10 +643,10 @@ impl Repository {
   #[napi]
   /// Create a diff with the difference between two tree objects.
   ///
-  /// This is equivalent to `git diff <old-tree> <new-tree>`
+  /// This is equivalent to `git diff <old-tree> <new-tree>`.
   ///
-  /// The first tree will be used for the "old_file" side of the delta and the
-  /// second tree will be used for the "new_file" side of the delta.  You can
+  /// The first tree will be used for the "oldFile" side of the delta and the
+  /// second tree will be used for the "newFile" side of the delta. You can
   /// pass `null` to indicate an empty tree, although it is an error to pass
   /// `null` for both the `oldTree` and `newTree`.
   pub fn diff_tree_to_tree(
@@ -675,8 +675,8 @@ impl Repository {
   #[napi]
   /// Create a diff between two index objects.
   ///
-  /// The first index will be used for the "old_file" side of the delta, and
-  /// the second index will be used for the "new_file" side of the delta.
+  /// The first index will be used for the "oldFile" side of the delta, and
+  /// the second index will be used for the "newFile" side of the delta.
   pub fn diff_index_to_index(
     &self,
     env: Env,
@@ -700,12 +700,12 @@ impl Repository {
   /// Create a diff between the repository index and the workdir directory.
   ///
   /// This matches the `git diff` command.  See the note below on
-  /// `tree_to_workdir` for a discussion of the difference between
+  /// `diffTreeToWorkdir` for a discussion of the difference between
   /// `git diff` and `git diff HEAD` and how to emulate a `git diff <treeish>`
   /// using libgit2.
   ///
-  /// The index will be used for the "old_file" side of the delta, and the
-  /// working directory will be used for the "new_file" side of the delta.
+  /// The index will be used for the "oldFile" side of the delta, and the
+  /// working directory will be used for the "newFile" side of the delta.
   ///
   /// If you pass `null` for the index, then the existing index of the `repo`
   /// will be used. In this case, the index will be refreshed from disk
@@ -731,18 +731,18 @@ impl Repository {
   #[napi]
   /// Create a diff between a tree and the working directory.
   ///
-  /// The tree you provide will be used for the "old_file" side of the delta,
-  /// and the working directory will be used for the "new_file" side.
+  /// The tree you provide will be used for the "oldFile" side of the delta,
+  /// and the working directory will be used for the "newFile" side.
   ///
   /// This is not the same as `git diff <treeish>` or `git diff-index <treeish>`.
   /// Those commands use information from the index, whereas this
   /// function strictly returns the differences between the tree and the files
-  /// in the working directory, regardless of the state of the index.  Use
-  /// `tree_to_workdir_with_index` to emulate those commands.
+  /// in the working directory, regardless of the state of the index. Use
+  /// `diffTreeToWorkdirWithIndex` to emulate those commands.
   ///
-  /// To see difference between this and `tree_to_workdir_with_index`,
+  /// To see difference between this and `diffTreeToWorkdirWithIndex`,
   /// consider the example of a staged file deletion where the file has then
-  /// been put back into the working dir and further modified.  The
+  /// been put back into the working dir and further modified. The
   /// tree-to-workdir diff for that file is 'modified', but `git diff` would
   /// show status 'deleted' since there is a staged delete.
   ///

src/diff.rs

@@ -186,10 +186,10 @@ pub struct IndexUpdateAllOptions {
 }
 
 #[napi]
-/// A structure to represent a git [index][1]
+/// A class to represent a git [index][1].
 /// @hideconstructor
 ///
-/// [1]: http://git-scm.com/book/en/Git-Internals-Git-Objects
+/// [1]: https://git-scm.com/book/en/Git-Internals-Git-Objects
 pub struct Index {
   pub(crate) inner: git2::Index,
 }
@@ -199,7 +199,7 @@ impl Index {
   #[napi]
   /// Get index on-disk version.
   ///
-  /// Valid return values are 2, 3, or 4.  If 3 is returned, an index
+  /// Valid return values are 2, 3, or 4. If 3 is returned, an index
   /// with version 2 may be written instead, if the extension data in
   /// version 3 is not necessary.
   pub fn version(&self) -> u32 {
@@ -209,7 +209,7 @@ impl Index {
   #[napi]
   /// Set index on-disk version.
   ///
-  /// Valid values are 2, 3, or 4.  If 2 is given, git_index_write may
+  /// Valid values are 2, 3, or 4. If 2 is given, git_index_write may
   /// write an index with version 3 instead, if necessary to accurately
   /// represent the index.
   pub fn set_version(&mut self, version: u32) -> crate::Result<()> {
@@ -227,7 +227,7 @@ impl Index {
   }
 
   #[napi]
-  /// Add or update an index entry from a file on disk
+  /// Add or update an index entry from a file on disk.
   ///
   /// The file path must be relative to the repository's working folder and
   /// must be readable.
@@ -394,7 +394,7 @@ impl Index {
   }
 
   #[napi]
-  /// Update all index entries to match the working directory
+  /// Update all index entries to match the working directory.
   ///
   /// This method will fail in bare index instances.
   ///
@@ -433,13 +433,13 @@ impl Index {
   }
 
   #[napi]
-  /// Get the count of entries currently in the index
+  /// Get the count of entries currently in the index.
   pub fn count(&self) -> u32 {
     self.inner.len() as u32
   }
 
   #[napi]
-  /// Return `true` is there is no entry in the index
+  /// Return `true` is there is no entry in the index.
   pub fn is_empty(&self) -> bool {
     self.inner.is_empty()
   }
@@ -469,7 +469,7 @@ impl Index {
 }
 
 #[napi(iterator)]
-/// An iterator over the entries in an index
+/// An iterator over the entries in an index.
 ///
 /// @hideconstructor
 pub struct IndexEntries {
@@ -493,12 +493,7 @@ impl Repository {
   /// Get the Index file for this repository.
   ///
   /// If a custom index has not been set, the default index for the repository
-  /// will be returned (the one located in .git/index).
-  ///
-  /// **Caution**: If the [`git2::Repository`] of this index is dropped, then this
-  /// [`git2::Index`] will become detached, and most methods on it will fail. See
-  /// [`git2::Index::open`]. Be sure the repository has a binding such as a local
-  /// variable to keep it alive at least as long as the index.
+  /// will be returned (the one located in `.git/index`).
   pub fn index(&self) -> crate::Result<Index> {
     Ok(Index {
       inner: self.inner.index()?,