[PATCH 5/5] fix up docs

[Tom Tromey <tromey@redhat.com>]

This patch fixes up the BFD archive docs to describe memory management
for archive member BFDs.

	* archive.c: Update archive documentation.
---
 bfd/archive.c |   19 +++++++++++++++----
 1 files changed, 15 insertions(+), 4 deletions(-)

diff --git a/bfd/archive.c b/bfd/archive.c
index 8407745..d5133d0 100644
--- a/bfd/archive.c
+++ b/bfd/archive.c
@@ -42,11 +42,22 @@ DESCRIPTION
 	have to read the entire archive if you don't want
 	to!  Read it until you find what you want.
 
+	A BFD returned by <<bfd_openr_next_archived_file>> will not
+	automatically be closed.  If you want to close it, you must
+	call <<bfd_close>>.  If you do not close it, then a second
+	iteration through the members of an archive may return the
+	same BFD.
+
+	A member BFD is not fully independent of its containing
+	archive BFD.  So, if you close the archive BFD, you must
+	ensure that either the member BFDs have been closed first, or
+	that they are never referred to (and thus effectively leaked).
+
 	Archive contents of output BFDs are chained through the
-	<<next>> pointer in a BFD.  The first one is findable through
-	the <<archive_head>> slot of the archive.  Set it with
-	<<bfd_set_archive_head>> (q.v.).  A given BFD may be in only one
-	open output archive at a time.
+	<<archive_next>> pointer in a BFD.  The first one is findable
+	through the <<archive_head>> slot of the archive.  Set it with
+	<<bfd_set_archive_head>> (q.v.).  A given BFD may be in only
+	one open output archive at a time.
 
 	As expected, the BFD archive code is more general than the
 	archive code of any given environment.  BFD archives may
-- 
1.7.7.6