From 06a3f7618973a9367c1e7af6b2a88f8c24c78894 Mon Sep 17 00:00:00 2001
From: Michael Zillgith <michael.zillgith@mz-automation.de>
Date: Mon, 16 Nov 2015 09:48:46 +0100
Subject: [PATCH] - updated documentation for SV subscriber

---
 .../sv_subscriber/sv_subscriber_example.c     | 21 ++++++++++++++++---
 src/doxygen.config                            |  3 ++-
 src/sampled_values/sv_subscriber.h            |  8 +++++++
 3 files changed, 28 insertions(+), 4 deletions(-)

diff --git a/examples/sv_subscriber/sv_subscriber_example.c b/examples/sv_subscriber/sv_subscriber_example.c
index 131bc5e8..46784c92 100644
--- a/examples/sv_subscriber/sv_subscriber_example.c
+++ b/examples/sv_subscriber/sv_subscriber_example.c
@@ -1,5 +1,5 @@
 /*
- * subscriber_test.c
+ * sv_subscriber_example.c
  *
  * Example program for Sampled Values (SV) subscriber
  *
@@ -33,6 +33,16 @@ svUpdateListener (SVSubscriber subscriber, void* parameter, SVClientASDU asdu)
     printf("  smpCnt: %i\n", SVClientASDU_getSmpCnt(asdu));
     printf("  confRev: %u\n", SVClientASDU_getConfRev(asdu));
 
+    /*
+     * Access to the data requires a priori knowledge of the data set.
+     * For this example we assume a data set consisting of FLOAT32 values.
+     * A FLOAT32 value is encoded as 4 bytes. You can find the first FLOAT32
+     * value at byte position 0, the second value at byte position 4, the third
+     * value at byte position 8, and so on.
+     *
+     * To prevent damages due configuration, please check the length of the
+     * data block of the SV message before accessing the data.
+     */
     if (SVClientASDU_getDataSize(asdu) >= 8) {
         printf("   DATA[0]: %f\n", SVClientASDU_getFLOAT32(asdu, 0));
         printf("   DATA[1]: %f\n", SVClientASDU_getFLOAT32(asdu, 4));
@@ -53,21 +63,26 @@ main(int argc, char** argv)
         SVReceiver_setInterfaceId(receiver, "eth0");
     }
 
+    /* Create a subscriber listening to SV messages with APPID 4000h */
     SVSubscriber subscriber = SVSubscriber_create(NULL, 0x4000);
 
+    /* Install a callback handler for the subscriber */
     SVSubscriber_setListener(subscriber, svUpdateListener, NULL);
 
+    /* Connect the subscriber to the receiver */
     SVReceiver_addSubscriber(receiver, subscriber);
 
+    /* Start listening to SV messages - starts a new receiver background thread */
     SVReceiver_start(receiver);
 
     signal(SIGINT, sigint_handler);
 
-    while (running) {
+    while (running)
         Thread_sleep(1);
-    }
 
+    /* Stop listening to SV messages */
     SVReceiver_stop(receiver);
 
+    /* Cleanup and free resources */
     SVReceiver_destroy(receiver);
 }
diff --git a/src/doxygen.config b/src/doxygen.config
index f6275955..c9c1c332 100644
--- a/src/doxygen.config
+++ b/src/doxygen.config
@@ -18,7 +18,7 @@ DOXYFILE_ENCODING      = UTF-8
 
 PROJECT_NAME           = "libIEC61850"
 
-PROJECT_NUMBER         = 0.8.7
+PROJECT_NUMBER         = 0.9.0
 
 PROJECT_BRIEF          = "Open-source IEC 61850 MMS/GOOSE server and client library"
 
@@ -219,6 +219,7 @@ INPUT   += "iec61850/inc/iec61850_config_file_parser.h"
 INPUT   += "iec61850/inc/iec61850_cdc.h"
 INPUT   += "goose/goose_subscriber.h"
 INPUT   += "goose/goose_receiver.h"
+INPUT   += "sampled_values/sv_subscriber.h"
 INPUT   += "mms/inc/mms_device_model.h"
 INPUT   += "mms/inc/mms_types.h"
 INPUT   += "mms/inc/mms_common.h" 
diff --git a/src/sampled_values/sv_subscriber.h b/src/sampled_values/sv_subscriber.h
index b619e294..f15ca21a 100644
--- a/src/sampled_values/sv_subscriber.h
+++ b/src/sampled_values/sv_subscriber.h
@@ -30,6 +30,12 @@
 extern "C" {
 #endif
 
+/**
+ * \defgroup sv_subscriber_api_group IEC 61850 sampled values (SV) subscriber API
+ */
+/**@{*/
+
+
 /**
  * \brief opaque handle to a SV ASDU (Application service data unit) instance.
  *
@@ -318,6 +324,8 @@ SVClientASDU_getFLOAT64(SVClientASDU self, int index);
 int
 SVClientASDU_getDataSize(SVClientASDU self);
 
+/**@}*/
+
 #ifdef __cplusplus
 }
 #endif