libdvbv5: Document dvb-log.h and dvb-sat.h

Add documentation to those two additional headers.

Signed-off-by: Mauro Carvalho Chehab <m.chehab@samsung.com>

diff --git a/lib/include/libdvbv5/dvb-log.h b/lib/include/libdvbv5/dvb-log.h
index cca350e..4b3e43d 100644 (file)
--- a/lib/include/libdvbv5/dvb-log.h
+++ b/lib/include/libdvbv5/dvb-log.h
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011-2012 - Mauro Carvalho Chehab
+ * Copyright (c) 2011-2014 - Mauro Carvalho Chehab
  * Copyright (c) 2012 - Andre Roth <neolynx@gmail.com>
  *
  * This program is free software; you can redistribute it and/or
@@ -26,6 +26,10 @@
 
 typedef void (*dvb_logfunc)(int level, const char *fmt, ...) __attribute__ (( format( printf, 2, 3 )));
 
+/*
+ * Macros used internally inside libdvbv5 frontend part, to output logs
+ */
+
 #ifndef __DVB_FE_PRIV_H
 
 #define dvb_log(fmt, arg...) do {\
@@ -72,6 +76,10 @@ typedef void (*dvb_logfunc)(int level, const char *fmt, ...) __attribute__ (( fo
 
 #endif
 
+/*
+ * This is the prototype of the internal log function that it is used,
+ * if the library client doesn't desire to override with something else.
+ */
 void dvb_default_log(int level, const char *fmt, ...) __attribute__ (( format( printf, 2, 3 )));
 
 #endif

diff --git a/lib/include/libdvbv5/dvb-sat.h b/lib/include/libdvbv5/dvb-sat.h
index f14e7e4..721149a 100644 (file)
--- a/lib/include/libdvbv5/dvb-sat.h
+++ b/lib/include/libdvbv5/dvb-sat.h
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011-2012 - Mauro Carvalho Chehab
+ * Copyright (c) 2011-2014 - Mauro Carvalho Chehab
  *
  * This program is free software; you can redistribute it and/or
  * modify it under the terms of the GNU General Public License
@@ -21,10 +21,41 @@
 
 #include "dvb-v5-std.h"
 
+/*
+ * Satellite handling functions
+ */
+
+/**
+ * struct dvbsat_freqrange - Defines a frequency range used by Satellite
+ *
+ * @low:       low frequency, in kHz
+ * @high:      high frequency, in kHz
+ */
 struct dvbsat_freqrange {
        unsigned low, high;
 };
 
+/**
+ * struct dvb_sat_lnb - Stores the information of a LNBf
+ *
+ * @name:              long name of the LNBf type
+ * @alias:             short name for the LNBf type
+ * @lowfreq:           Low frequency Intermediate Frequency of the LNBf, in kHz
+ * @highfreq:          High frequency Intermediate frequency of the LNBf,
+ *                     in kHz
+ * @rangeswitch:       For LNBf that has multiple frequency ranges controlled
+ *                     by a voltage change, specify the start frequency where
+ *                     the second range will be applied.
+ * @freqrange:         Contains the range(s) of frequencies supported by a
+ *                     given LNBf.
+ *
+ * The LNBf (low-noise block downconverter) is a type of amplifier that is
+ * installed inside the parabolic dishes. It converts the antenna signal to
+ * an Intermediate Frequency. Several Ku-band LNBf have more than one IF.
+ * The lower IF is stored at lowfreq, the higher IF at highfreq.
+ * The exact setup for those structs actually depend on the model of the LNBf,
+ * and its usage.
+ */
 struct dvb_sat_lnb {
        const char *name;
        const char *alias;
@@ -38,14 +69,56 @@ struct dvb_sat_lnb {
 struct dvb_v5_fe_parms;
 
 #ifdef __cplusplus
-extern "C" {
+extern "C"
 #endif
 
 /* From libsat.c */
+
+/**
+ * dvb_sat_search_lnb() - search for a LNBf entry
+ *
+ * @name:      name of the LNBf entry to seek.
+ *
+ * On sucess, it returns a non-negative number with corresponds to the LNBf
+ * entry inside the LNBf structure at dvb-sat.c.
+ * A -1 return code indicates that the LNBf was not found.
+ */
 int dvb_sat_search_lnb(const char *name);
+
+/**
+ * dvb_print_lnb() - prints the contents of a LNBf entry at STDOUT.
+ *
+ * @i:         index for the entry
+ *
+ * returns -1 if the index is out of range, zero otherwise.
+ */
 int dvb_print_lnb(int i);
+
+/**
+ * dvb_print_all_lnb() - Prints all LNBf entries at STDOUT.
+ *
+ * This function doesn't return anything. Internally, it calls dvb_print_lnb()
+ * for all entries inside its LNBf database.
+ */
 void dvb_print_all_lnb(void);
+
+/**
+ * dvb_sat_get_lnb() - gets a LNBf entry at its internal database
+ *
+ * @i:         index for the entry.
+ *
+ * returns NULL if not found, of a struct dvb_sat_lnb pointer otherwise.
+ */
 const struct dvb_sat_lnb *dvb_sat_get_lnb(int i);
+
+/**
+ * dvb_sat_set_parms() - sets the satellite parameters
+ *
+ * @parms:     struct dvb_v5_fe_parms pointer.
+ *
+ * This function is called internally by the library to set the LNBf
+ * parameters, if the dvb_v5_fe_parms::lnb field is filled.
+ */
 int dvb_sat_set_parms(struct dvb_v5_fe_parms *parms);
 
 #ifdef __cplusplus