A bunch of doxygen comments

docs/doxygen/Doxyfile.in

@@ -28,7 +28,7 @@ DOXYFILE_ENCODING      = UTF-8
 # identify the project. Note that if you do not use Doxywizard you need
 # to put quotes around the project name if it contains spaces.
 
-PROJECT_NAME           = "GNU Radio's SIGMF Package"
+PROJECT_NAME           = "Skysafe's SigMF Package"
 
 # The PROJECT_NUMBER tag can be used to enter a project or revision number.
 # This could be handy for archiving the generated documentation or
@@ -40,7 +40,7 @@ PROJECT_NUMBER         =
 # for a project that appears at the top of each page and should give viewer
 # a quick idea about the purpose of the project. Keep the description short.
 
-PROJECT_BRIEF          =
+PROJECT_BRIEF          = "GNURadio blocks for SigMF"
 
 # With the PROJECT_LOGO tag one can specify an logo or icon that is
 # included in the documentation. The maximum height of the logo should not

docs/doxygen/other/main_page.dox

@@ -1,10 +1,13 @@
 /*! \mainpage
 
-Welcome to the GNU Radio SIGMF Block
+Welcome to the GNU Radio SigMF Block
 
-This is the intro page for the Doxygen manual generated for the SIGMF
-block (docs/doxygen/other/main_page.dox). Edit it to add more detailed
-documentation about the new GNU Radio modules contained in this
-project.
+This OOT module contains a set of blocks for working with sigmf.
+The main blocks in this module are:
+
+- source: A block for reading SigMF data
+- sink: A block for writing SigMF data
+- usrp_gps_message_source: A block to make getting gps metadata from a USRP radio easier
+- annotation_sink: A block for writing annotation data only
 
 */

include/sigmf/meta_namespace.h

@@ -46,18 +46,39 @@ namespace gr {
     class SIGMF_API meta_namespace {
       public:
 
-      static meta_namespace
-      build_global_object(std::string datatype, std::string version = SIGMF_VERSION);
-
+      /* \brief build meta_namespace that represents a global metadata sction
+      * @param datatype the datatype of the file as a string
+      * @param version the sigmf version of the file
+      * @return the built meta_namespace object
+      */
+      static meta_namespace build_global_object(std::string datatype, std::string version = SIGMF_VERSION);
+
+      /* \brief build meta_namespace that represents a capture segment
+      * @param sample_start the sample_start of this capture segment
+      * @return the built meta_namespace object
+      */
       static meta_namespace build_capture_segment(uint64_t sample_start);
+
+      /* \brief build meta_namespace that represents an annotation segment
+      * @param sample_start the sample_start of this annotation segment
+      * @param sample_count the sample_count of this annotation segment
+      * @return the built meta_namespace object
+      */
       static meta_namespace build_annotation_segment(uint64_t sample_start, uint64_t sample_count);
 
       meta_namespace(pmt::pmt_t data);
       meta_namespace();
       ~meta_namespace();
 
+      /* \brief access the underlying pmt for this meta_namespace object
+      * @return the pmt
+      */
       pmt::pmt_t data();
 
+      /* \brief check if a given string is a valid key for SigMF metadata
+      * @param key the key to check
+      * @return true if the key is valid and false otherwise
+      */
       static bool validate_key(const std::string &key);
 
       template <typename ValType>

include/sigmf/sigmf_utils.h

@@ -24,16 +24,48 @@
 #include <boost/filesystem/path.hpp>
 namespace gr {
   namespace sigmf {
+
+    /*! \brief convert a filename to the path of a .sigmf-data file
+      * @param filename the filename
+      * @return the path as a boost::filesystem::path object
+      *
+      * For example, filename is `/foo/bar/baz` then the returned path would
+      * be `/foo/bar/bas.sigmf-data`. Any existing extension will be replaced
+      */
     boost::filesystem::path to_data_path(const std::string &filename) SIGMF_API;
+
+    /*! \brief convert a data path to the path of a .sigmf-meta file
+      * @param data_path path to data
+      * @return the path as a boost::filesystem::path object
+      */
     boost::filesystem::path meta_path_from_data(boost::filesystem::path data_path) SIGMF_API;
 
-    enum endian_t { LITTLE = 0, BIG = 1 };
+    //! An enum describing endianness
+    enum endian_t {
+      //! Little endian
+      LITTLE = 0,
+      //! Big endian
+      BIG = 1
+    };
+
+    //! struct representing a parsed SigMF format
     struct SIGMF_API format_detail_t {
+      //! true if the format is a complex type, false otherwise
       bool is_complex;
-      std::string type_str; // base type string, so no r or c and no _le or _be
+      //! base type string, so no r or c and no _le or _be
+      std::string type_str;
+      //! size of the format in bits
       size_t width;
+      //! endinness of the format
       endian_t endianness;
     };
+
+    /*! \brief Parse the dataset format
+     * defined by SigMF into a format_detail_t struct.
+     * @param format_str format as a sttring
+     * @exception std::runtime_error invalid format string
+     * @return the parsed struct
+     */
     format_detail_t parse_format_str(const std::string &format_str) SIGMF_API;
 
   }

include/sigmf/sink.h

@@ -51,24 +51,91 @@ namespace gr {
                        sigmf_time_mode time_mode = sigmf_time_mode::absolute,
                        bool append = false);
 
+      /* \brief Get the path the the current .sigmf-data file as a string
+       *
+       * If there is no currently open file, returns empty string
+       * @return the path
+       */
       virtual std::string get_data_path() = 0;
+
+      /* \brief Get the path the the current .sigmf-meta file as a string
+       *
+       * If there is no currently open file, returns empty string
+       * @return the path
+       */
       virtual std::string get_meta_path() = 0;
 
+      /* \brief Set a value in the global metadata for this data set.
+       * @param key the key for the value
+       * @param val the value to store
+       */
       virtual void set_global_meta(const std::string &key, pmt::pmt_t val) = 0;
+
+      /* \brief Set a value in the global metadata for this data set.
+       * @param key the key for the value
+       * @param val the value to store
+       */
       virtual void set_global_meta(const std::string &key, double val) = 0;
+
+      /* \brief Set a value in the global metadata for this data set.
+       * @param key the key for the value
+       * @param val the value to store
+       */
       virtual void set_global_meta(const std::string &key, int64_t val) = 0;
+
+      /* \brief Set a value in the global metadata for this data set.
+       * @param key the key for the value
+       * @param val the value to store
+       */
       virtual void set_global_meta(const std::string &key, uint64_t val) = 0;
+
+      /* \brief Set a value in the global metadata for this data set.
+       * @param key the key for the value
+       * @param val the value to store
+       */
       virtual void set_global_meta(const std::string &key, const std::string &val) = 0;
+
+      /* \brief Set a value in the global metadata for this data set.
+       * @param key the key for the value
+       * @param val the value to store
+       */
       virtual void set_global_meta(const std::string &key, bool val) = 0;
 
+      /* \brief Set a value in the annotations metadata for this data set.
+       * @param sample_start sample start for the annotation
+       * @param sample_count sample count for the annotation
+       * @param key the key for the value
+       * @param val the value to store
+       *
+       * If there is an existing annotation with the same sample start and count,
+       * then the new value will be added to it. Otherwise, a new annotation will
+       * be created.
+       */
       virtual void set_annotation_meta(uint64_t sample_start,
                                        uint64_t sample_count,
                                        std::string key,
                                        pmt::pmt_t val) = 0;
 
+      /* \brief Set a value in the annotations metadata for this data set.
+       * @param index the index of the desired capture segment
+       * @param key the key for the value
+       * @param val the value to store
+       *
+       * If no capture segment with the given index exists, then the new value is
+       * dropped and an error is logged.
+       */
       virtual void set_capture_meta(uint64_t index, std::string key, pmt::pmt_t val) = 0;
 
+      /* \brief Open a new file to start recording to
+       * @param filename the file to write to
+       *
+       * The sigmf sink will coerce the filename to the names of the two files in a
+       * SigMF data set
+       */
       virtual bool open(const char *filename) = 0;
+
+      /* \brief Stop writing to the current file
+       */
       virtual void close() = 0;
     };
 

include/sigmf/source.h

@@ -50,19 +50,27 @@ namespace gr {
 
       /*!
        * \brief Return a shared_ptr to a new instance of sigmf::source.
-       * 
-       * This constructor will build a sink that will always use the 
+       *
+       * This constructor will build a sink that will always use the
        * native datatype of the input file as the output datatype.
        */
       static sptr
       make_no_datatype(std::string filename, bool repeat = false);
 
       /*!
        * \brief Add a stream tag to the first sample of the file if true
+       * @param val the tag to add
        */
       virtual void set_begin_tag(pmt::pmt_t val) = 0;
 
+      /*!
+       * \brief retrieve the global metadata for this source
+       */
       virtual gr::sigmf::meta_namespace &global_meta() = 0;
+
+      /*!
+       * \brief retrieve the capture segments for this source
+       */
       virtual std::vector<gr::sigmf::meta_namespace> &capture_segments() = 0;
     };