From: Mikko Rasa <tdb@tdb.fi>
Date: Tue, 26 Mar 2013 20:36:17 +0000 (+0200)
Subject: Comment improvements
X-Git-Url: http://git.tdb.fi/?p=libs%2Fdatafile.git;a=commitdiff_plain;h=7184146e19a45f968a4bc4d0cee252f13dbeb7c5

Comment improvements
---

diff --git a/source/collection.h b/source/collection.h
index 0d2dc6b..7a09f50 100644
--- a/source/collection.h
+++ b/source/collection.h
@@ -46,8 +46,8 @@ method for details.
 Collections can have sources for loading objects on demand.  Automatic loading
 only works on a non-const Collection.  See class CollectionSource for details.
 
-A fallback collection can be designated as another way of loading items that
-are not present.  Items retrieted from the fallback collection are shared
+As a last resort, a fallback collection can be designated for loading items
+that are not present.  Items retrieted from the fallback collection are shared
 between the collections, and are only deleted when all collections in the chain
 have been destroyed.
 */
@@ -262,8 +262,13 @@ private:
 	CollectionItemTypeBase *get_type_for_item(const Variant &) const;
 
 protected:
+	/** Adds a source for automatically loading items.  Sources are consulted
+	in the order they are added. */
 	void add_source(CollectionSource &);
 
+	/** Opens a raw resource, without interpreting it as object data.  Null is
+	returned if no such file is found.  The caller must dispose of the returned
+	object when done with it. */
 	IO::Seekable *open_from_sources(const std::string &);
 
 private:
diff --git a/source/collectionsource.h b/source/collectionsource.h
index 90c36f2..e5647d8 100644
--- a/source/collectionsource.h
+++ b/source/collectionsource.h
@@ -25,17 +25,18 @@ protected:
 public:
 	virtual ~CollectionSource() { }
 
-	/** Determines */
+	/// Determines whether an object is available from this source.
 	virtual bool is_loadable(const CollectionItemTypeBase &type, const std::string &name) const = 0;
 
-	/** Returns the names of loadable objects of a specific type.  Implementors
-	should use the keyword and/or suffixes of the type to  */
+	/** Returns the names of available objects of a specific type.  Implementors
+	should use type.match_name to check which names are acceptable. */
 	virtual NameList get_names(const CollectionItemTypeBase &type) const = 0;
 
+	/// Loads an item into a collection.
 	virtual void load(Collection &, const CollectionItemTypeBase &, const std::string &) const = 0;
 
-	/** Opens a file from the source.  The caller is responsible for deleting
-	the returned object when done with it. */
+	/** Opens a raw resource.  The caller is responsible for deleting the
+	returned object when done with it. */
 	virtual IO::Seekable *open(const std::string &) const = 0;
 };