Fix a few documentation things 85/18485/9
authorMats Wichmann <mats@linux.com>
Thu, 30 Mar 2017 16:02:58 +0000 (10:02 -0600)
committerUze Choi <uzchoi@samsung.com>
Mon, 22 May 2017 08:41:31 +0000 (08:41 +0000)
- doc markup and reword for time function (oc_time.h)
- exclude a C++ header (RDClient.h) from c-doc Doxyfile
- update markup for octimer (octimer.h)
- in earlier revision had added octimer.h to c-doc Doxyfile,
  that was (maybe) in error, removed again
- add placeholder @file markup to octypes.h, ocpayload.h, ocpresence.h
  in preparation for actually writing something about those headers

There are no code changes.

Change-Id: I003348985937f127765e7d2bca74b05bce8b45d0
Signed-off-by: Mats Wichmann <mats@linux.com>
Reviewed-on: https://gerrit.iotivity.org/gerrit/18485
Tested-by: jenkins-iotivity <jenkins@iotivity.org>
Reviewed-by: Uze Choi <uzchoi@samsung.com>
resource/c_common/octimer/include/octimer.h
resource/c_common/oic_time/include/oic_time.h
resource/csdk/include/octypes.h
resource/csdk/stack/include/ocpayload.h
resource/csdk/stack/include/ocpresence.h
resource/docs/c-doc/Doxyfile

index 446ea79..bd13a76 100644 (file)
 //
 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
 
+/**
+ * @file
+ * Time value functions.
+ */
+
 #ifndef OCTIMER_H_
 #define OCTIMER_H_
 
@@ -50,7 +55,9 @@ extern "C"
 typedef void(*TimerCallback)();
 
 /**
- * This must be async-signal safe, so it cannot use difftime().
+ * Calculate time difference.
+ *
+ * Needs to be be async-signal safe, so cannot use difftime().
  * @param[in] after time to be substracted
  * @param[in] before reference time to be compared to
  * @return number of seconds between before and after, (after - before).
@@ -58,11 +65,14 @@ typedef void(*TimerCallback)();
 time_t timespec_diff(const time_t after, const time_t before);
 
 /**
- * Add positive seconds to a timespec, nothing if seconds is negative.
+ * Increase a time value by a specified amount.
+ *
+ * Adds positive seconds to a time value, nothing if seconds is negative.
  * @param[out] to time result to be added
  * @param[in] seconds amount of sec to add
  */
 void timespec_add(time_t *to, const time_t seconds);
+
 void checkTimeout();
 
 #ifndef WITH_ARDUINO
index 6ca9e3e..cbf0924 100644 (file)
 //
 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
 
+/**
+ * @file
+ * Support for working with elapsed time.
+ */
+
 #ifndef OIC_TIME_H_
 #define OIC_TIME_H_
 
 #include <stdint.h>
 
+/**
+ * @name
+ * Useful constants for time unit conversions.
+ *
+ * @{
+ */
 #define MS_PER_SEC  (1000)
 #define US_PER_SEC  (1000000)
 #define US_PER_MS   (1000)
 #define NS_PER_US   (1000)
 #define NS_PER_MS   (1000000)
 #define HNS_PER_US  (10)
+/** @} */
 
 
 #ifdef __cplusplus
@@ -38,32 +50,40 @@ extern "C"
 
 typedef enum
 {
-    TIME_IN_MS = 0,
-    TIME_IN_US,
-}OICTimePrecision;
+    TIME_IN_MS = 0,     //!< milliseconds
+    TIME_IN_US,         //!< microseconds
+} OICTimePrecision;
 
-/*
- * If monotonic coarse/monotonic clock supported then gets current time as monotonic time
- * in milliseconds or microseconds as the elapsed time since some unspecified starting point
- * else gets current time in milliseconds or microseconds as the elapsed time since the epoch.
+/**
+ * Get the current time using the specified precision.
+ *
+ * Return the time in units of `precision`.
+ * If the implementation supports a monotonic clock, then
+ * the returned value will be from the monotonic clock,
+ * and the difference between two retrieved times can be considered
+ * an accurate elapsed time. The time base is unspecified
+ * in this case. If a monotonic clock is not supported,
+ * the time returned will be `precision` time units since the epoch,
+ * without adjustment for any external changes to the clock.
  *
- * For Arduino gets current time in milliseconds or microseconds since Arduino board begin
+ * For Arduino, returns the time since the Arduino board begin
  * running this program.
  *
- * @param     precision   based on this parameter, current time is returned in milliseconds or
- *                        microseconds
+ * @param     precision   based on this parameter, current time is
+ * returned in milliseconds or microseconds
  *
- * @warning   This function may be sensitive to system time changes on some platforms.
+ * @warning   This function may be sensitive to system time changes on
+ * platforms which do not support a monotonic clock.
  *
  * @note
- *            On Arduino platform:
- *            if the time precision is in milliseconds then the function will overflow
- *            (go back to 0) after approximately 50 days.
- *            if the time precision is in microseconds then the function will overflow
- *            (go back to 0) after approximately 70minutes.
+ * On the Arduino platform,
+ * if the time precision is in milliseconds then the function will
+ * overflow (go back to 0) after approximately 50 days.
+ * If the time precision is in microseconds then the function will
+ * overflow (go back to 0) after approximately 70 minutes.
  *
  * @return
- *         returns current time in milliseconds or microseconds.
+ *         Returns current time in milliseconds or microseconds.
  */
 uint64_t OICGetCurrentTime(OICTimePrecision precision);
 
index fa1705e..7a39e54 100644 (file)
@@ -22,7 +22,7 @@
 /**
  * @file
  *
- * This file contains the definition, types and APIs for resource(s) be implemented.
+ * This file contains the definitions, types and APIs for resources to be implemented.
  */
 
 #ifndef OCTYPES_H_
index 1312b2c..70b6948 100644 (file)
 //
 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
 
+/**
+ * @file
+ *
+ */
+
 #ifndef OCPAYLOAD_H_
 #define OCPAYLOAD_H_
 
index 8213152..14536ee 100644 (file)
 //
 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
 
+/**
+ * @file
+ *
+ */
+
 #ifndef OCPRESENCE_H_
 #define OCPRESENCE_H_
 
index 816dcf2..8949d63 100644 (file)
@@ -658,6 +658,8 @@ WARN_LOGFILE           = ./doxygen.log
 # documented source files. You may enter file names like "myfile.cpp" or
 # directories like "/usr/src/myproject". Separate the files or directories
 # with spaces.
+#
+# see also EXCLUDE for any files to be omitted from these paths
 
 INPUT                  = . \
              ../../csdk/include/octypes.h \
@@ -749,7 +751,8 @@ RECURSIVE              = NO
 # Note that relative paths are relative to the directory from which doxygen is
 # run.
 
-EXCLUDE                =
+EXCLUDE                = \
+             ../../csdk/resource-directory/include/RDClient.h
 
 # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
 # directories that are symbolic links (a Unix file system feature) are excluded