added comments to cmakelists, makedir in file generation script so python doesnt have to

9 files changed, 38 insertions, 23 deletions

diff --git a/host/docs/CMakeLists.txt b/host/docs/CMakeLists.txt
index 52376fe8c..476023a1e 100644
--- a/host/docs/CMakeLists.txt
+++ b/host/docs/CMakeLists.txt
@@ -35,25 +35,33 @@ IF(${RST2HTML} STREQUAL "RST2HTML-NOTFOUND")
 ELSE(${RST2HTML} STREQUAL "RST2HTML-NOTFOUND")
     MESSAGE(STATUS "Checking for rst2html (docutils) - found")
     MESSAGE(STATUS "  Enabled generation of HTML manual.")
-    SET(stylesheet ${CMAKE_CURRENT_SOURCE_DIR}/style.css)
+
+    #setup rst2html options
     SET(rst2html_options
-        --stylesheet=${stylesheet}
-        --no-toc-backlinks
-        --date
-        --time
+        --stylesheet=${CMAKE_CURRENT_SOURCE_DIR}/style.css
+        --no-toc-backlinks --date --time
     )
+
+    #create generation rule for each source
     FOREACH(rstfile ${manual_sources})
+        #set input and output file names
         SET(rstfile ${CMAKE_CURRENT_SOURCE_DIR}/${rstfile})
         GET_FILENAME_COMPONENT(rstfile_we ${rstfile} NAME_WE)
         SET(htmlfile ${CMAKE_CURRENT_BINARY_DIR}/${rstfile_we}.html)
+
+        #make the html file depend on the rst file
         ADD_CUSTOM_COMMAND(
             OUTPUT ${htmlfile} DEPENDS ${rstfile} ${stylesheet}
             COMMAND ${RST2HTML} ${rstfile} ${htmlfile} ${rst2html_options}
             COMMENT "Generating ${htmlfile}"
         )
+
+        #make the manual target depend on the html file
         LIST(APPEND manual_html_files ${htmlfile})
         INSTALL(FILES ${htmlfile} DESTINATION ${PKG_DOC_DIR}/manual/html)
     ENDFOREACH(rstfile ${manual_sources})
+
+    #make the html manual a build-time dependency
     ADD_CUSTOM_TARGET(manual_html ALL DEPENDS ${manual_html_files})
 ENDIF(${RST2HTML} STREQUAL "RST2HTML-NOTFOUND")
 
@@ -66,16 +74,24 @@ INCLUDE(FindDoxygen)
 
 IF(DOXYGEN_FOUND)
     MESSAGE(STATUS "  Enabled generation of Doxygen documentation.")
+
+    #generate the doxygen configuration file
     SET(CMAKE_CURRENT_BINARY_DIR_DOXYGEN ${CMAKE_CURRENT_BINARY_DIR}/doxygen)
     CONFIGURE_FILE(
         ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in
         ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
     @ONLY)
-    ADD_CUSTOM_COMMAND(OUTPUT ${CMAKE_CURRENT_BINARY_DIR_DOXYGEN}
+
+    #make doxygen directory depend on the header files
+    FILE(GLOB_RECURSE header_files ${CMAKE_SOURCE_DIR}/include/*.hpp)
+    ADD_CUSTOM_COMMAND(
+        OUTPUT ${CMAKE_CURRENT_BINARY_DIR_DOXYGEN} DEPENDS ${header_files}
         COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
         COMMENT "Generating documentation with doxygen"
     )
-    ADD_CUSTOM_TARGET(doxygen_html ALL DEPENDS ${CMAKE_CURRENT_BINARY_DIR_DOXYGEN})
+
+    #make the doxygen generation a built-time dependency
+    ADD_CUSTOM_TARGET(doxygen_docs ALL DEPENDS ${CMAKE_CURRENT_BINARY_DIR_DOXYGEN})
     INSTALL(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR_DOXYGEN} DESTINATION ${PKG_DOC_DIR})
 ELSE(DOXYGEN_FOUND)
     MESSAGE(STATUS "  Disabled generation of Doxygen documentation.")
diff --git a/host/include/uhd/types/metadata.hpp b/host/include/uhd/types/metadata.hpp
index d93b38b50..55add71cc 100644
--- a/host/include/uhd/types/metadata.hpp
+++ b/host/include/uhd/types/metadata.hpp
@@ -70,7 +70,10 @@ namespace uhd{
          * Timed-out on receive?
          */
 
-        //default constructor
+        /*!
+         * The default constructor:
+         * Sets the fields to default values (flags set to false).
+         */
         rx_metadata_t(void);
     };
 
@@ -103,7 +106,10 @@ namespace uhd{
         bool start_of_burst;
         bool end_of_burst;
 
-        //default constructor
+        /*!
+         * The default constructor:
+         * Sets the fields to default values (flags set to false).
+         */
         tx_metadata_t(void);
     };
 
diff --git a/host/lib/CMakeLists.txt b/host/lib/CMakeLists.txt
index 7b8149802..7cb74d30a 100644
--- a/host/lib/CMakeLists.txt
+++ b/host/lib/CMakeLists.txt
@@ -66,11 +66,18 @@ SET(libuhd_sources
 # Generate Files
 ########################################################################
 MACRO(UHD_PYTHON_GEN_SOURCE_FILE pyfile outfile)
+    #ensure that the directory exists for outfile
+    GET_FILENAME_COMPONENT(outfile_dir ${outfile} PATH)
+    FILE(MAKE_DIRECTORY ${outfile_dir})
+
+    #make the outfile depend on the python script
     ADD_CUSTOM_COMMAND(
         OUTPUT ${outfile} DEPENDS ${pyfile}
         COMMAND ${PYTHON_EXECUTABLE} ${pyfile} ${outfile}
         COMMENT "Generating ${outfile}"
     )
+
+    #make libuhd depend on the outfile
     LIST(APPEND libuhd_sources ${outfile})
 ENDMACRO(UHD_PYTHON_GEN_SOURCE_FILE)
 
diff --git a/host/lib/ic_reg_maps/common.py b/host/lib/ic_reg_maps/common.py
index b7fa27bbe..bf51073ae 100644
--- a/host/lib/ic_reg_maps/common.py
+++ b/host/lib/ic_reg_maps/common.py
@@ -19,16 +19,12 @@
 # Boston, MA 02110-1301, USA.
 
 import re
-import os
 import math
 from Cheetah.Template import Template
 
 def parse_tmpl(_tmpl_text, **kwargs):
     return str(Template(_tmpl_text, kwargs))
 
-def safe_makedirs(path):
-    not os.path.isdir(path) and os.makedirs(path)
-
 class reg:
     def __init__(self, reg_des):
         x = re.match('^(\w*)\s*(\w*)\[(.*)\]\s*(\w*)\s*(.*)$', reg_des)
diff --git a/host/lib/ic_reg_maps/gen_ad5624_regs.py b/host/lib/ic_reg_maps/gen_ad5624_regs.py
index 378a6912f..a809d2f47 100755
--- a/host/lib/ic_reg_maps/gen_ad5624_regs.py
+++ b/host/lib/ic_reg_maps/gen_ad5624_regs.py
@@ -19,7 +19,6 @@
 # the Free Software Foundation, Inc., 51 Franklin Street,
 # Boston, MA 02110-1301, USA.
 
-import os
 import sys
 from common import *
 
@@ -83,5 +82,4 @@ struct ad5624_regs_t{
 
 if __name__ == '__main__':
     regs = map(reg, parse_tmpl(REGS_DATA_TMPL).splitlines())
-    safe_makedirs(os.path.dirname(sys.argv[1]))
     open(sys.argv[1], 'w').write(parse_tmpl(HEADER_TEXT, regs=regs, file=__file__))
diff --git a/host/lib/ic_reg_maps/gen_ad7922_regs.py b/host/lib/ic_reg_maps/gen_ad7922_regs.py
index e1e67d617..512dcdc46 100755
--- a/host/lib/ic_reg_maps/gen_ad7922_regs.py
+++ b/host/lib/ic_reg_maps/gen_ad7922_regs.py
@@ -19,7 +19,6 @@
 # the Free Software Foundation, Inc., 51 Franklin Street,
 # Boston, MA 02110-1301, USA.
 
-import os
 import sys
 from common import *
 
@@ -89,5 +88,4 @@ struct ad7922_regs_t{
 
 if __name__ == '__main__':
     regs = map(reg, parse_tmpl(REGS_DATA_TMPL).splitlines())
-    safe_makedirs(os.path.dirname(sys.argv[1]))
     open(sys.argv[1], 'w').write(parse_tmpl(HEADER_TEXT, regs=regs, file=__file__))
diff --git a/host/lib/ic_reg_maps/gen_ad9510_regs.py b/host/lib/ic_reg_maps/gen_ad9510_regs.py
index 32a8a04c6..4f28d5597 100755
--- a/host/lib/ic_reg_maps/gen_ad9510_regs.py
+++ b/host/lib/ic_reg_maps/gen_ad9510_regs.py
@@ -19,7 +19,6 @@
 # the Free Software Foundation, Inc., 51 Franklin Street,
 # Boston, MA 02110-1301, USA.
 
-import os
 import sys
 from common import *
 
@@ -174,5 +173,4 @@ struct ad9510_regs_t{
 
 if __name__ == '__main__':
     regs = map(reg, parse_tmpl(REGS_DATA_TMPL).splitlines())
-    safe_makedirs(os.path.dirname(sys.argv[1]))
     open(sys.argv[1], 'w').write(parse_tmpl(HEADER_TEXT, regs=regs, file=__file__))
diff --git a/host/lib/ic_reg_maps/gen_ad9777_regs.py b/host/lib/ic_reg_maps/gen_ad9777_regs.py
index e4369291a..65a9657a4 100755
--- a/host/lib/ic_reg_maps/gen_ad9777_regs.py
+++ b/host/lib/ic_reg_maps/gen_ad9777_regs.py
@@ -19,7 +19,6 @@
 # the Free Software Foundation, Inc., 51 Franklin Street,
 # Boston, MA 02110-1301, USA.
 
-import os
 import sys
 from common import *
 
@@ -152,5 +151,4 @@ struct ad9777_regs_t{
 
 if __name__ == '__main__':
     regs = map(reg, parse_tmpl(REGS_DATA_TMPL).splitlines())
-    safe_makedirs(os.path.dirname(sys.argv[1]))
     open(sys.argv[1], 'w').write(parse_tmpl(HEADER_TEXT, regs=regs, file=__file__))
diff --git a/host/lib/ic_reg_maps/gen_adf4360_regs.py b/host/lib/ic_reg_maps/gen_adf4360_regs.py
index f82e8c7c5..c659766dc 100755
--- a/host/lib/ic_reg_maps/gen_adf4360_regs.py
+++ b/host/lib/ic_reg_maps/gen_adf4360_regs.py
@@ -19,7 +19,6 @@
 # the Free Software Foundation, Inc., 51 Franklin Street,
 # Boston, MA 02110-1301, USA.
 
-import os
 import sys
 from common import *
 
@@ -123,5 +122,4 @@ struct adf4360_regs_t{
 
 if __name__ == '__main__':
     regs = map(reg, parse_tmpl(REGS_DATA_TMPL).splitlines())
-    safe_makedirs(os.path.dirname(sys.argv[1]))
     open(sys.argv[1], 'w').write(parse_tmpl(HEADER_TEXT, regs=regs, file=__file__))