Add documentation comments for commit_and_push() function

Author: vignesh-sankaran

src/git.rs

@@ -77,8 +77,6 @@ pub fn add_crate(app: &App, krate: &Crate) -> CargoResult<()> {
 /// file, deserlialise the crate from JSON, change the yank boolean to
 /// `true` or `false`, write all the lines back out, and commit and
 /// push the changes.
-// TODO: factor out the tasks this function does into smaller, separate
-// functions.
 pub fn yank(app: &App, krate: &str, version: &semver::Version, yanked: bool) -> CargoResult<()> {
     let repo = app.git_repo.lock().unwrap();
     let repo_path = repo.workdir().unwrap();
@@ -118,6 +116,21 @@ pub fn yank(app: &App, krate: &str, version: &semver::Version, yanked: bool) ->
     })
 }
 
+/// Commits and pushes to the crates.io index.
+///
+/// There are currently 2 instances of the crates.io backend running
+/// on Heroku, and they race against each other e.g. if 2 pushes occur,
+/// then one will succeed while the other will need to be rebased before
+/// being pushed.
+/// 
+/// A maximum of 20 attempts to commit and push to the index currently
+/// accounts for the amount of traffic publishing crates, though this will
+/// eventually need to be changed past a certain point.
+///
+/// Notes:
+/// Currently, this function is called from the HTTP thread and is blocking.
+/// This could be changed to run from a different thread and use a callback
+/// upon completion to the HTTP thread.
 fn commit_and_push<F>(repo: &git2::Repository, mut f: F) -> CargoResult<()>
 where
     F: FnMut() -> CargoResult<(String, PathBuf)>,