This is an automated email from the ASF dual-hosted git repository.
dbarnes pushed a commit to branch develop
in repository https://gitbox.apache.org/repos/asf/geode-native.git
The following commit(s) were added to refs/heads/develop by this push:
new d5d2e99 GEODE-4728: First pass at API docs improvements. - Clean up
comments - Fix incorrect comment format causing missed APIs in docs - Fixed
incorrect out parameter - Added missing CTOR API - Miscellaneous typos - Remove
deprecated doxygen flags from doxyfile
d5d2e99 is described below
commit d5d2e9941db6eb07f32d250535c51d687752d851
Author: Mike Martell <[email protected]>
AuthorDate: Wed May 16 15:22:02 2018 -0700
GEODE-4728: First pass at API docs improvements.
- Clean up comments
- Fix incorrect comment format causing missed APIs in docs
- Fixed incorrect out parameter
- Added missing CTOR API
- Miscellaneous typos
- Remove deprecated doxygen flags from doxyfile
---
cppcache/include/geode/Cache.hpp | 2 +-
cppcache/include/geode/CacheWriter.hpp | 12 ++++--
cppcache/include/geode/CqAttributes.hpp | 6 ++-
cppcache/include/geode/CqAttributesMutator.hpp | 9 +++--
cppcache/include/geode/PartitionResolver.hpp | 52 ++++++++++++++------------
cppcache/include/geode/RegionFactory.hpp | 10 ++++-
docs/api/clicache/Doxyfile.in | 4 --
docs/api/cppcache/Doxyfile.in | 4 --
8 files changed, 55 insertions(+), 44 deletions(-)
diff --git a/cppcache/include/geode/Cache.hpp b/cppcache/include/geode/Cache.hpp
index 2b80bfd..32659fb 100644
--- a/cppcache/include/geode/Cache.hpp
+++ b/cppcache/include/geode/Cache.hpp
@@ -54,7 +54,7 @@ enum class RegionShortcut;
/**
* @class Cache Cache.hpp
*
- * Cache are obtained from create method on the {@link CacheFactory#create}
+ * Caches are obtained from the create method on the {@link
CacheFactory#create}
* class
* <p>
* When a cache will no longer be used, it should be {@link #close closed}.
diff --git a/cppcache/include/geode/CacheWriter.hpp
b/cppcache/include/geode/CacheWriter.hpp
index c9e1496..7d8e08f 100644
--- a/cppcache/include/geode/CacheWriter.hpp
+++ b/cppcache/include/geode/CacheWriter.hpp
@@ -104,7 +104,8 @@ class APACHE_GEODE_EXPORT CacheWriter {
*/
virtual bool beforeUpdate(const EntryEvent& event);
- /** Called before an entry is created. Entry creation is initiated by a
+ /**
+ * Called before an entry is created. Entry creation is initiated by a
* <code>create</code>, a <code>put</code>, or a <code>get</code>.
* The <code>CacheWriter</code> can determine whether this value comes from a
* <code>get</code> or not from {@link EntryEvent::isLoad}. The entry being
@@ -136,7 +137,8 @@ class APACHE_GEODE_EXPORT CacheWriter {
*/
virtual bool beforeDestroy(const EntryEvent& event);
- /*@brief called before this region is cleared
+ /**
+ * @brief called before this region is cleared
* @param event EntryEvent denotes the event object associated with clearing
* the region
*
@@ -144,7 +146,8 @@ class APACHE_GEODE_EXPORT CacheWriter {
*/
virtual bool beforeRegionClear(const RegionEvent& event);
- /*@brief called before this region is destroyed
+ /**
+ * @brief called before this region is destroyed
* @param event EntryEvent denotes the event object associated with
destroying
* the region
*
@@ -152,7 +155,8 @@ class APACHE_GEODE_EXPORT CacheWriter {
*/
virtual bool beforeRegionDestroy(const RegionEvent& event);
- /** Called when the region containing this callback is destroyed, when
+ /**
+ * Called when the region containing this callback is destroyed, when
* the cache is closed.
*
* <p>Implementations should clean up any external
diff --git a/cppcache/include/geode/CqAttributes.hpp
b/cppcache/include/geode/CqAttributes.hpp
index 688f50f..4bd555c 100644
--- a/cppcache/include/geode/CqAttributes.hpp
+++ b/cppcache/include/geode/CqAttributes.hpp
@@ -42,14 +42,16 @@ namespace client {
*/
class APACHE_GEODE_EXPORT CqAttributes {
public:
+ /**
+ * CqListeners type
+ */
typedef std::vector<std::shared_ptr<CqListener>> listener_container_type;
/**
* Get the CqListeners set with the CQ.
* Returns all the Listeners associated with this CQ.
* @see CqListener
- * @param[out] std::vector<std::shared_ptr<CqListener>> of
- * std::shared_ptr<CqListner>
+ * @returns listener_container_type
*/
virtual listener_container_type getCqListeners() = 0;
};
diff --git a/cppcache/include/geode/CqAttributesMutator.hpp
b/cppcache/include/geode/CqAttributesMutator.hpp
index 42870b8..ea9c57d 100644
--- a/cppcache/include/geode/CqAttributesMutator.hpp
+++ b/cppcache/include/geode/CqAttributesMutator.hpp
@@ -42,6 +42,9 @@ class CqListener;
*/
class APACHE_GEODE_EXPORT CqAttributesMutator {
public:
+ /** Constructs a <code>CqAttributesMutator</code> with the given {@link
+ * CqAttributes}.
+ */
CqAttributesMutator(const std::shared_ptr<CqAttributes>& impl);
/**
@@ -62,9 +65,9 @@ class APACHE_GEODE_EXPORT CqAttributesMutator {
void removeCqListener(const std::shared_ptr<CqListener>& aListener);
/**
- * Adds the given set CqListner on this CQ. If the CQ already has
CqListeners,
- * this
- * removes those old CQs and initializes with the newListeners.
+ * Adds the given set CqListener on this CQ. If the CQ already has
+ * CqListeners, this removes those old CQs and initializes with the
+ * newListeners.
* @param newListeners a possibly empty array of listeners to add
* to this CqQuery.
* @throws IllegalArgumentException if the <code>newListeners</code> array
diff --git a/cppcache/include/geode/PartitionResolver.hpp
b/cppcache/include/geode/PartitionResolver.hpp
index 210eda5..49ae916 100644
--- a/cppcache/include/geode/PartitionResolver.hpp
+++ b/cppcache/include/geode/PartitionResolver.hpp
@@ -35,37 +35,41 @@ class CacheableKey;
class EntryEvent;
/**
- * Implementers of interface <code>PartitionResolver</code> enable custom
+ * Implement the <code>PartitionResolver</code> interface to enable custom
* partitioning on the <code>PartitionedRegion</code>.
- * 1. The Key class or callback arg can implement PartitionResolver interface
to
- * enable custom partitioning OR
- * 2. Configure your own PartitionResolver class in partition attributes (For
- * instance when the Key is a primitive type or String) Implement the
- * appropriate equals - For all implementations, you need to be sure to code
the
- * class equals method so it properly verifies equality for the
+ *
+ * The Key class or callback arg can implement the PartitionResolver interface
+ * to enable custom partitioning, or you can configure your own
+ * PartitionResolver class in partition attributes (for instance when the Key
is
+ * a primitive type or String):
+ * - Implement the appropriate equals. For all implementations, you need to be
+ * sure to code the class equals method so it properly verifies equality for
the
* PartitionResolver implementation. This might mean verifying that class names
- * are the same or that the returned routing objects are the same etc.. When
you
+ * are the same or that the returned routing objects are the same etc. When you
* initiate the partitioned region on multiple nodes, Geode uses the equals
* method to ensure you are using the same PartitionResolver implementation for
* all of the nodes for the region.
- * Geode uses the routing object's hashCode to determine where the data is
+ * - Geode uses the routing object's hashCode to determine where the data is
* being managed. Say, for example, you want to colocate all Trades by month
and
- * year.The key is implemented by TradeKey class which also implements the
- * PartitionResolver interface.
- * public class TradeKey implements PartitionResolver {<br>
- *     private String tradeID;<br>
- *     private Month month ;<br>
- *     private Year year ;<br>
+ * year. The key is implemented by a TradeKey class which also implements the
+ * PartitionResolver interface:
+ *
+ * @code
+ * public class TradeKey implements PartitionResolver {
+ * private String tradeID;
+ * private Month month;
+ * private Year year;
*
- *     public TradingKey(){ } <br>
- *     public TradingKey(Month month, Year year){<br>
- *         this.month = month;<br>
- *         this.year = year;<br>
- *     } <br>
- *     public Serializable getRoutingObject(EntryOperation
- * opDetails){<br>
- *         return this.month + this.year;<br>
- *     }<br> }<br>
+ * public TradingKey() { }
+ * public TradingKey(Month month, Year year) {
+ * this.month = month;
+ * this.year = year;
+ * }
+ * public Serializable getRoutingObject(EntryOperation opDetails) {
+ * return this.month + this.year;
+ * }
+ * }
+ * @endcode
*
* In the example above, all trade entries with the same month and year are
* guaranteed to be colocated.
diff --git a/cppcache/include/geode/RegionFactory.hpp
b/cppcache/include/geode/RegionFactory.hpp
index 9ea5a76..b41b76c 100644
--- a/cppcache/include/geode/RegionFactory.hpp
+++ b/cppcache/include/geode/RegionFactory.hpp
@@ -34,6 +34,12 @@ namespace apache {
namespace geode {
namespace client {
class CacheImpl;
+
+/**
+ * @class RegionFactory RegionFactory.hpp
+ *
+ * Provides for the configuration and creation of instances of Region.
+ */
class APACHE_GEODE_EXPORT RegionFactory {
public:
RegionFactory() = delete;
@@ -41,8 +47,8 @@ class APACHE_GEODE_EXPORT RegionFactory {
RegionFactory(const RegionFactory& nocopy) = delete;
RegionFactory(RegionFactory&& move) = default;
- /*
- * To create the (@link Region}.
+ /**
+ * Create a {@link Region} of the given <code>name</code>.
* @param name
* the name of the Region.
* @throws RegionExistsException if a region is already in
diff --git a/docs/api/clicache/Doxyfile.in b/docs/api/clicache/Doxyfile.in
index 5e5442e..703797b 100644
--- a/docs/api/clicache/Doxyfile.in
+++ b/docs/api/clicache/Doxyfile.in
@@ -25,9 +25,6 @@ JAVADOC_AUTOBRIEF = YES
# Always generate a detailed description of functions
ALWAYS_DETAILED_SEC = YES
-# Include a detailed description of the class/file like Javadoc does
-DETAILS_AT_TOP = YES
-
# We're generating documentation for C
OPTIMIZE_OUTPUT_FOR_C = YES
@@ -101,7 +98,6 @@ SOURCE_BROWSER = NO
VERBATIM_HEADERS = NO
SHOW_INCLUDE_FILES = NO
SHOW_USED_FILES = NO
-SHOW_DIRECTORIES = NO
INTERNAL_DOCS = NO
INLINE_INHERITED_MEMB = YES
INHERIT_DOCS = YES
diff --git a/docs/api/cppcache/Doxyfile.in b/docs/api/cppcache/Doxyfile.in
index 0f25c0a..da8c8d7 100644
--- a/docs/api/cppcache/Doxyfile.in
+++ b/docs/api/cppcache/Doxyfile.in
@@ -25,9 +25,6 @@ JAVADOC_AUTOBRIEF = YES
# Always generate a detailed description of functions
ALWAYS_DETAILED_SEC = YES
-# Include a detailed description of the class/file like Javadoc does
-DETAILS_AT_TOP = YES
-
# We're generating documentation for C
OPTIMIZE_OUTPUT_FOR_C = YES
@@ -87,7 +84,6 @@ WARN_LOGFILE = cppDoxygenWarnings.log
SOURCE_BROWSER = NO
SHOW_INCLUDE_FILES = NO
SHOW_USED_FILES = NO
-SHOW_DIRECTORIES = NO
INTERNAL_DOCS = NO
INLINE_INHERITED_MEMB = YES
INHERIT_DOCS = YES
--
To stop receiving notification emails like this one, please contact
[email protected].
