[PATCH] submodule: correct documentation for open_submodule

[Stefan Beller <sbeller@google.com>]

When 99017ffac8 (submodule: use submodule repos for object lookup, 2018-11-13)
was merged, I had not yet addressed all outstanding review comments, such
as adapting the documentation for the function `open_submodule`, which
changed its signature during the development of that series.
Fix the documentation, and annotate setting of `submodule_prefix`
to indicate we're dealing with a submodule repository.

Signed-off-by: Stefan Beller <sbeller@google.com>
---

> I'll incorporate these changes once resending.

... only to realize it hit next already, so we'd prefer updates instead
of resending the whole series.

Maybe a patch like this?

 submodule.c | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/submodule.c b/submodule.c
index 262f03f118..4486ff664b 100644
--- a/submodule.c
+++ b/submodule.c
@@ -483,12 +483,13 @@ void prepare_submodule_repo_env(struct argv_array *out)
 }
 
 /*
- * Initialize 'out' based on the provided submodule path.
+ * Initialize a repository struct for a submodule based on the provided 'path'.
  *
  * Unlike repo_submodule_init, this tolerates submodules not present
  * in .gitmodules. This function exists only to preserve historical behavior,
  *
- * Returns 0 on success, -1 when the submodule is not present.
+ * Returns the repository struct on success,
+ * NULL when the submodule is not present.
  */
 static struct repository *open_submodule(const char *path)
 {
@@ -501,6 +502,7 @@ static struct repository *open_submodule(const char *path)
 		return NULL;
 	}
 
+	/* Mark it as a submodule */
 	out->submodule_prefix = xstrdup(path);
 
 	strbuf_release(&sb);
-- 
2.20.0.rc2.230.gc28305e538