remote: clarify which list of references _ls() returns

Make it clear that this is not the ls-remote command but a way to access
the data we have and how long it's kept around.

2 files changed, 12 insertions, 7 deletions

diff --git a/include/git2/remote.h b/include/git2/remote.h
index ef242293c..d3157d9cc 100644
--- a/include/git2/remote.h
+++ b/include/git2/remote.h
@@ -281,14 +281,19 @@ GIT_EXTERN(const git_refspec *)git_remote_get_refspec(const git_remote *remote,
 GIT_EXTERN(int) git_remote_connect(git_remote *remote, git_direction direction);
 
 /**
- * Get a list of refs at the remote
+ * Get the remote repository's reference advertisement list
  *
- * The remote (or more exactly its transport) must be connected. The
- * memory belongs to the remote.
+ * Get the list of references with which the server responds to a new
+ * connection.
  *
- * The array will stay valid as long as the remote object exists and
- * its transport isn't changed, but a copy is recommended for usage of
- * the data.
+ * The remote (or more exactly its transport) must have connected to
+ * the remote repository. This list is available as soon as the
+ * connection to the remote is initiated and it remains available
+ * after disconnecting.
+ *
+ * The memory belongs to the remote. The pointer will be valid as long
+ * as a new connection is not initiated, but it is recommended that
+ * you make a copy in order to make use of the data.
  *
  * @param out pointer to the array
  * @param size the number of remote heads
diff --git a/src/remote.c b/src/remote.c
index 3715e43ea..b1a84075e 100644
--- a/src/remote.c
+++ b/src/remote.c
@@ -706,7 +706,7 @@ int git_remote_ls(const git_remote_head ***out, size_t *size, git_remote *remote
 	assert(remote);
 
 	if (!remote->transport) {
-		giterr_set(GITERR_NET, "No transport bound to this remote");
+		giterr_set(GITERR_NET, "this remote has never connected");
 		return -1;
 	}