From b48d1eb90c63e70b03519923dab5e123b11d91a4 Mon Sep 17 00:00:00 2001
From: Mikko Rasa <tdb@tdb.fi>
Date: Wed, 26 Sep 2012 10:43:01 +0300
Subject: [PATCH] Improve the documentation of Collection

---
 source/collection.h | 59 +++++++++++++++++++++++++--------------------
 1 file changed, 33 insertions(+), 26 deletions(-)

diff --git a/source/collection.h b/source/collection.h
index b223990..5dd2fe6 100644
--- a/source/collection.h
+++ b/source/collection.h
@@ -34,12 +34,17 @@ class CollectionItemType;
 /**
 A collection of objects that can be loaded from a datafile.  Each object is
 identified by a name, which must be unique across the entire collection.
+
+While this class can be instantiated by itself and used for storing objects,
+loading requires that a subclass defines the supported types.  See the add_type
+method for details.
 */
 class Collection
 {
 public:
 	/**
-	Loads objects into a Collection.
+	Loads objects into a Collection.  Automatically picks up keywords from
+	defined item types.
 	*/
 	class Loader: public DataFile::Loader
 	{
@@ -87,10 +92,8 @@ public:
 	Collection() { }
 	virtual ~Collection();
 
-	/**
-	Adds an object into the collection.  If a name collision occurs, an
-	exception is thrown.  The collection takes ownership of the object.
-	*/
+	/** Adds an object into the collection.  The name must not pre-exist.  The
+	collection takes ownership of the object. */
 	template<typename T>
 	void add(const std::string &name, T *item)
 	{
@@ -110,9 +113,7 @@ public:
 		}
 	}
 
-	/**
-	Gets an object of a specific type from the collection.
-	*/
+	/// Gets a typed object from the collection.
 	template<typename T>
 	T &get(const std::string &name) const
 	{
@@ -121,17 +122,12 @@ public:
 		return *get_item(items, name).value<RefPtr<NCT> >();
 	}
 
-	/**
-	Gets an object of a specific type from the collection.  If the name is not
-	found in the collection and there is a creator for the item type, it is
-	invoked.
-	*/
+	/** Gets a typed object from the collection.  If the name is not found in
+	and a creator for the item type is defined, it is invoked. */
 	template<typename T>
 	T &get(const std::string &);
 
-	/**
-	Returns a list of the names of objects of a specific type in the collection.
-	*/
+	/// Returns a list of the names of objects of one type in the collection.
 	template<typename T>
 	std::list<std::string> get_names() const
 	{
@@ -142,9 +138,7 @@ public:
 		return result;
 	}
 
-	/**
-	Returns a list of objects of a specific type in the collection.
-	*/
+	/// Returns a list of objects of one type in the collection.
 	template<typename T>
 	std::list<T *> get_list() const
 	{
@@ -157,15 +151,11 @@ public:
 		return result;
 	}
 
-	/**
-	Checks whether a name exists in the collection.  Does not care about the
-	type of the object.
-	*/
+	/** Checks whether a name exists in the collection.  Does not care about the
+	type of the object. */
 	bool contains(const std::string &n) const;
 
-	/**
-	Returns the name of an item in the collection.
-	*/
+	/// Returns the name of an item in the collection.
 	template<typename T>
 	const std::string &get_name(T *d) const
 	{
@@ -181,6 +171,8 @@ public:
 	}
 
 protected:
+	/** Adds a type to the collection.  The returned descriptor object reference
+	can be used to define how objects of that type can be loaded. */
 	template<typename T>
 	CollectionItemType<T> &add_type();
 };
@@ -237,6 +229,10 @@ public:
 };
 
 
+/**
+Describes a type of item that can be loaded by a Collection.  These are created
+by Collection::add_type.
+*/
 template<typename T>
 class CollectionItemType: public CollectionItemTypeBase
 {
@@ -304,12 +300,21 @@ public:
 		delete store;
 	}
 
+	/** Sets a datafile keyword for this item type.  The Collection's loader
+	will accept a statement with this keyword and a single string argument - the
+	item's name. */
 	CollectionItemType &keyword(const std::string &k)
 	{
 		kwd = k;
 		return *this;
 	}
 
+	/** Attaches a creator function to this item type.  If an item is not found
+	in the Collection, the creator function for its type is called to create it.
+	The function must be a member of the Collection subclass containing the
+	type.  It must return the created object, or null if it could not be
+	created.  It's also permissible to load the item via other means and then
+	return null. */
 	template<typename C>
 	CollectionItemType &creator(T *(C::*func)(const std::string &))
 	{
@@ -318,6 +323,8 @@ public:
 		return *this;
 	}
 
+	/** Specifies the storage type for items of this type.  It must be a base
+	class of the actual type.  */
 	template<typename S>
 	CollectionItemType &store_as()
 	{
-- 
2.45.2