[Commit-gnuradio] [gnuradio] 01/01: docs: Corrects or expands documentation comments for various blocks where I have had to read the source code to understand the

[git]

This is an automated email from the git hooks/post-receive script.

trondeau pushed a commit to branch maint
in repository gnuradio.

commit e6a396f21c3794462c4db4930a590551ba548952
Author: Kevin Reid <address@hidden>
Date:   Mon Jul 7 10:52:10 2014 -0400

    docs: Corrects or expands documentation comments for various blocks where I 
have had to read the source code to understand the
    
    - char_to_short and short_to_char scale by a factor of 1<<8.
    - What delay actually does.
    - File descriptor blocks close their FDs when destroyed.
    
    And one code change:
    
    The firdes transition width check error text is made consistent with other 
similar messages.
    
    Addresses Issue #686.
---
 gr-blocks/include/gnuradio/blocks/char_to_short.h          | 7 ++++---
 gr-blocks/include/gnuradio/blocks/delay.h                  | 3 +++
 gr-blocks/include/gnuradio/blocks/file_descriptor_sink.h   | 3 ++-
 gr-blocks/include/gnuradio/blocks/file_descriptor_source.h | 3 ++-
 gr-blocks/include/gnuradio/blocks/short_to_char.h          | 4 ++++
 gr-filter/lib/firdes.cc                                    | 2 +-
 6 files changed, 16 insertions(+), 6 deletions(-)

diff --git a/gr-blocks/include/gnuradio/blocks/char_to_short.h 
b/gr-blocks/include/gnuradio/blocks/char_to_short.h
index 05880e0..6f326c8 100644
--- a/gr-blocks/include/gnuradio/blocks/char_to_short.h
+++ b/gr-blocks/include/gnuradio/blocks/char_to_short.h
@@ -30,13 +30,14 @@ namespace gr {
   namespace blocks {
 
     /*!
-     * \brief Convert stream of chars to a stream of short
+     * \brief Convert stream of chars to a stream of shorts.
      * \ingroup type_converters_blk
      *
      * \details
-     * Converts \p vlen length vectors of input char samples to shorts:
+     * Converts \p vlen length vectors of input char samples to shorts,
+     * multiplying each element by 256:
      *
-     * \li output[0][m:m+vlen] = static_cast<short>(input[0][m:m+vlen])
+     * \li output[0][m:m+vlen] = 256 * static_cast<short>(input[0][m:m+vlen])
      */
     class BLOCKS_API char_to_short : virtual public sync_block
     {
diff --git a/gr-blocks/include/gnuradio/blocks/delay.h 
b/gr-blocks/include/gnuradio/blocks/delay.h
index bae5e40..fc90e22 100644
--- a/gr-blocks/include/gnuradio/blocks/delay.h
+++ b/gr-blocks/include/gnuradio/blocks/delay.h
@@ -32,6 +32,9 @@ namespace gr {
     /*!
      * \brief delay the input by a certain number of samples
      * \ingroup misc_blk
+     *
+     * Positive delays insert zero items at the beginning of the stream.
+     * Negative delays discard items from the stream.
      */
     class BLOCKS_API delay : virtual public block
     {
diff --git a/gr-blocks/include/gnuradio/blocks/file_descriptor_sink.h 
b/gr-blocks/include/gnuradio/blocks/file_descriptor_sink.h
index 31ec0cc..6399aec 100644
--- a/gr-blocks/include/gnuradio/blocks/file_descriptor_sink.h
+++ b/gr-blocks/include/gnuradio/blocks/file_descriptor_sink.h
@@ -40,7 +40,8 @@ namespace gr {
       typedef boost::shared_ptr<file_descriptor_sink> sptr;
 
       /*!
-       * Build a file descriptor sink block.
+       * Build a file descriptor sink block. The provided file descriptor will
+       * be closed when the sink is destroyed.
        *
        * \param itemsize item size of the incoming data stream.
        * \param fd file descriptor (as an integer).
diff --git a/gr-blocks/include/gnuradio/blocks/file_descriptor_source.h 
b/gr-blocks/include/gnuradio/blocks/file_descriptor_source.h
index 6292b63..d78b10a 100644
--- a/gr-blocks/include/gnuradio/blocks/file_descriptor_source.h
+++ b/gr-blocks/include/gnuradio/blocks/file_descriptor_source.h
@@ -46,7 +46,8 @@ namespace gr {
       typedef boost::shared_ptr<file_descriptor_source> sptr;
 
       /*!
-       * Build a file descriptor source block.
+       * Build a file descriptor source block. The provided file descriptor 
will
+       * be closed when the sink is destroyed.
        *
        * \param itemsize item size of the incoming data stream.
        * \param fd file descriptor (as an integer).
diff --git a/gr-blocks/include/gnuradio/blocks/short_to_char.h 
b/gr-blocks/include/gnuradio/blocks/short_to_char.h
index 22a157d..a80e6dc 100644
--- a/gr-blocks/include/gnuradio/blocks/short_to_char.h
+++ b/gr-blocks/include/gnuradio/blocks/short_to_char.h
@@ -38,6 +38,10 @@ namespace gr {
      * [0x00ff, 0x0ff0, 0xff00] => [0x00, 0x0f, 0xff]
      *
      * \ingroup type_converters_blk
+     *
+     * \details
+     * Converts \p vlen length vectors of input short samples to chars,
+     * dividing each element by 256.
      */
     class BLOCKS_API short_to_char : virtual public sync_block
     {
diff --git a/gr-filter/lib/firdes.cc b/gr-filter/lib/firdes.cc
index cb6bffd..1726d0b 100644
--- a/gr-filter/lib/firdes.cc
+++ b/gr-filter/lib/firdes.cc
@@ -720,7 +720,7 @@ namespace gr {
        throw std::out_of_range("firdes check failed: 0 < fa <= sampling_freq / 
2");
 
       if(transition_width <= 0)
-       throw std::out_of_range("gr_dirdes check failed: transition_width > 0");
+       throw std::out_of_range("firdes check failed: transition_width > 0");
     }
 
     void