SCI: Clarify docs of GC related SegmentObj methods

svn-id: r50440

2 files changed, 15 insertions, 5 deletions

diff --git a/engines/sci/engine/script.h b/engines/sci/engine/script.h
index d1e6a4509e..3817f8aae1 100644
--- a/engines/sci/engine/script.h
+++ b/engines/sci/engine/script.h
@@ -107,6 +107,12 @@ public:
 	virtual Common::Array<reg_t> listAllDeallocatable(SegmentId segId) const;
 	virtual Common::Array<reg_t> listAllOutgoingReferences(reg_t object) const;
 
+	/**
+	 * Return a list of all references to objects in this script
+	 * (and also to the locals segment, if any).
+	 * Used by the garbage collector.
+	 * @return a list of outgoing references within the object
+	 */
 	Common::Array<reg_t> listObjectReferences() const;
 
 	virtual void saveLoadWithSerializer(Common::Serializer &ser);
diff --git a/engines/sci/engine/segment.h b/engines/sci/engine/segment.h
index d290475593..b1e89e6357 100644
--- a/engines/sci/engine/segment.h
+++ b/engines/sci/engine/segment.h
@@ -105,6 +105,7 @@ public:
 
 	/**
 	 * Finds the canonic address associated with sub_reg.
+	 * Used by the garbage collector.
 	 *
 	 * For each valid address a, there exists a canonic address c(a) such that c(a) = c(c(a)).
 	 * This address "governs" a in the sense that deallocating c(a) will deallocate a.
@@ -115,14 +116,15 @@ public:
 
 	/**
 	 * Deallocates all memory associated with the specified address.
+	 * Used by the garbage collector.
 	 * @param sub_addr		address (within the given segment) to deallocate
 	 */
 	virtual void freeAtAddress(SegManager *segMan, reg_t sub_addr) {}
 
 	/**
-	 * Iterates over and reports all addresses within the current segment.
-	 * @param note		Invoked for each address on which free_at_address() makes sense
-	 * @param param		parameter passed to 'note'
+	 * Iterates over and reports all addresses within the segment.
+	 * Used by the garbage collector.
+	 * @return a list of addresses within the segment
 	 */
 	virtual Common::Array<reg_t> listAllDeallocatable(SegmentId segId) const {
 		return Common::Array<reg_t>();
@@ -130,9 +132,11 @@ public:
 
 	/**
 	 * Iterates over all references reachable from the specified object.
+	 * Used by the garbage collector.
 	 * @param  object	object (within the current segment) to analyse
-	 * @return refs		a list of outgoing references within the object
-	 * Note: This function may also choose to report numbers (segment 0) as adresses
+	 * @return a list of outgoing references within the object
+	 *
+	 * @note This function may also choose to report numbers (segment 0) as adresses
 	 */
 	virtual Common::Array<reg_t> listAllOutgoingReferences(reg_t object) const {
 		return Common::Array<reg_t>();