Small documentation improvements for better doxygen docs

git-svn-id: svn+ssh://svn.gnucash.org/repo/gnucash/trunk@18642 57a11ea4-9604-0410-9ed3-97b8803252fd

src/engine/gnc-pricedb.c

@@ -668,10 +668,11 @@ gnc_pricedb_set_bulk_update(GNCPriceDB *db, gboolean bulk_update)
 */
 /** \todo Collections of prices are not destroyed fully.
 
-gnc_pricedb_destroy does not clean up properly because
-gnc_pricedb_create reports an existing PriceDB after
-running gnc_pricedb_destroy. To change the pricedb, we need to
-destroy and recreate the book. Yuk.
+    \par
+    gnc_pricedb_destroy does not clean up properly because
+    gnc_pricedb_create reports an existing PriceDB after
+    running gnc_pricedb_destroy. To change the pricedb, we need to
+    destroy and recreate the book. Yuk.
  */
 
 GNCPriceDB *

src/engine/gnc-pricedb.h

@@ -82,14 +82,14 @@ GType gnc_pricedb_get_type(void);
     now in the hope that we get a real DB implementation before
     they're really needed.
 
-    Every QofBook contains a GNCPriceDB, accessable via
+    Every QofBook contains a GNCPriceDB, accessible via
     gnc_book_get_pricedb.
 
     \warning The PriceDB does not currently use the object
     system used elsewhere in the GnuCash Engine, i.e. it does
-    not use GUISD's, Entities and Collections.  Its should.
+    not use GUISD's, Entities and Collections.  It should.
     In particular, this means that currently prices cannot
-    be queried with the same emchanism as everything else.
+    be queried with the same mechanism as everything else.
 */
 
 /** @addtogroup Price  Prices
@@ -99,17 +99,13 @@ GType gnc_pricedb_get_type(void);
     a given price might represent the value of LNUX in USD on
     2001-02-03.
 
-    Fields:
+    \par Fields:
     
-      commodity: the item being priced.
-
-      currency: the denomination of the value of the item being priced.    
-
-      value: the value of the item being priced.
-
-      time: the time the price was valid.
-
-      source: a string describing the source of the quote.  These
+    - commodity: the item being priced.
+    - currency: the denomination of the value of the item being priced.
+    - value: the value of the item being priced.
+    - time: the time the price was valid.
+    - source: a string describing the source of the quote.  These
       strings will be something like this: "Finance::Quote",
       "user:misc", "user:foo", etc.  If the quote came from a user,
       as a matter of policy, you *must* prefix the string you give
@@ -117,16 +113,16 @@ GType gnc_pricedb_get_type(void);
       "Finance::Quote" and "old-file-import".  Any string used must
       be added to the source_list array in dialog-price-edit-db.c so
       that it can be properly translated. (There are unfortunately
-        many strings in users databased, so this string must be
-        translated on output instead of always being used intranslated
-        form.)
-
-      type: the type of quote - types possible right now are bid, ask,
+      many strings in users' databases, so this string must be
+      translated on output instead of always being used in untranslated
+      form).
+    - type: the type of quote - types possible right now are bid, ask,
       last, nav, and unknown.
 
-    Implementation Details:
+    \par Implementation Details:
 
-      NOTE: for source and type, NULL and the empty string are
+    \note
+    For source and type, NULL and the empty string are
     considered the same, so if one of these is "", then after a file
     save/restore, it might be NULL.  Behave accordingly.
 
@@ -189,9 +185,7 @@ void      gnc_price_unref(GNCPrice *p);
 
 /* ------------------ */
 /** @name  Setters
-    @{ */
-
-/* As mentioned above, all of the setters store copies of the data
+ * All of the setters store copies of the data
  * given, with the exception of the commodity field which just stores
  * the pointer given.  It is assumed that commodities are a global
  * resource and are pointer unique. 
@@ -200,7 +194,7 @@ void      gnc_price_unref(GNCPrice *p);
  * gnc_price_begin_edit() and commit_edit().  The begin/commit
  * calls help ensure that the local price db is synchronized with 
  * the backend.
- */
+   @{ */
 void gnc_price_begin_edit (GNCPrice *p);
 void gnc_price_commit_edit (GNCPrice *p);
 
@@ -214,10 +208,10 @@ void gnc_price_set_value(GNCPrice *p, gnc_numeric value);
 
 /* ------------------ */
 /** @name  Getters
+    All of the getters return data that's internal
+    to the GNCPrice, not copies, so don't free these values.
     @{ */
 
-/** As mentioned above all of the getters return data that's internal
-   to the GNCPrice, not copies, so don't free these values. */
 GNCPrice *      gnc_price_lookup (const GUID *guid, QofBook *book);
 /*@ dependent @*/ gnc_commodity * gnc_price_get_commodity(const GNCPrice *p);
 /*@ dependent @*/ gnc_commodity * gnc_price_get_currency(const GNCPrice *p);
@@ -232,6 +226,12 @@ gboolean        gnc_price_equal(const GNCPrice *p1, const GNCPrice *p2);
 #define gnc_price_get_book(X)    qof_instance_get_book(QOF_INSTANCE(X))
 /**  @} */
 
+/** @name Internal/Debugging
+    @{ */
+/** This simple function can be useful for debugging the price code */
+void gnc_price_print(GNCPrice *db, FILE *f, int indent);
+/** @} */
+
 /* ================================================================ */
 /** @name GNCPrice lists
     The database communicates multiple prices in and out via gnc price
@@ -439,10 +439,11 @@ guint gnc_pricedb_get_num_prices(GNCPriceDB *db);
 
 gboolean gnc_pricedb_equal (GNCPriceDB *db1, GNCPriceDB *db2);
 
-/** semi-lame debugging code */
-void gnc_price_print(GNCPrice *db, FILE *f, int indent);
+/** @name Internal/Debugging
+    @{ */
+/** This simple function can be useful for debugging the pricedb code */
 void gnc_pricedb_print_contents(GNCPriceDB *db, FILE *f);
-
+/** @} */
 
 /** @name Price Parameter Names
  *  For use with QofQuery