9 files changed, 55 insertions, 36 deletions
diff --git a/docs/doxygen/other/main_page.dox b/docs/doxygen/other/main_page.dox
index 8895cd552d..9353bfb315 100644
--- a/docs/doxygen/other/main_page.dox
+++ b/docs/doxygen/other/main_page.dox
@@ -45,6 +45,7 @@ More details on GNU Radio concepts:
 \li \ref page_metadata
 \li \ref volk_guide
 \li \ref page_pfb
+\li \ref page_tagged_stream_blocks
 
 
 \section flowgraph Operating a Flowgraph
diff --git a/gnuradio-core/src/lib/runtime/gr_tagged_stream_block.h b/gnuradio-core/src/lib/runtime/gr_tagged_stream_block.h
index a9d396c06f..a82b27f6a6 100644
--- a/gnuradio-core/src/lib/runtime/gr_tagged_stream_block.h
+++ b/gnuradio-core/src/lib/runtime/gr_tagged_stream_block.h
@@ -35,8 +35,8 @@
 class GR_CORE_API gr_tagged_stream_block : public gr_block
 {
  private:
-  pmt::pmt_t d_length_tag_key; //! This is the key for the tag that stores the PDU length
-  gr_vector_int d_n_input_items_reqd; //! How many input items do I need to process the next PDU?
+  pmt::pmt_t d_length_tag_key; //!< This is the key for the tag that stores the PDU length
+  gr_vector_int d_n_input_items_reqd; //!< How many input items do I need to process the next PDU?
 
  protected:
   std::string d_length_tag_key_str;
@@ -46,7 +46,8 @@ class GR_CORE_API gr_tagged_stream_block : public gr_block
 		 gr_io_signature_sptr output_signature,
 		 const std::string &length_tag_key);
 
-  /* \brief Parse all tags on the first sample of a PDU, return the number of items per input
+  /*!
+   * \brief Parse all tags on the first sample of a PDU, return the number of items per input
    *        and prune the length tags.
    *
    * In most cases, you don't need to override this, unless the number of items read
@@ -66,7 +67,8 @@ class GR_CORE_API gr_tagged_stream_block : public gr_block
       gr_vector_int &n_input_items_reqd
   );
 
-  /* \brief Calculate the number of output items.
+  /*!
+   * \brief Calculate the number of output items.
    *
    * This is basically the inverse function to forecast(): Given a number of input
    * items, it returns the maximum number of output items.
@@ -77,7 +79,8 @@ class GR_CORE_API gr_tagged_stream_block : public gr_block
    */
   virtual int calculate_output_stream_length(const gr_vector_int &ninput_items);
 
-  /* \brief Set the new length tags on the output stream
+  /*!
+   * \brief Set the new length tags on the output stream
    *
    * Default behaviour: Set a tag with key \p length_tag_key and
    * the number of produced items on every output port.
@@ -91,11 +94,12 @@ class GR_CORE_API gr_tagged_stream_block : public gr_block
 
  public:
 
-  /* \brief Don't override this.
+  /*! \brief Don't override this.
    */
   void /* final */ forecast (int noutput_items, gr_vector_int &ninput_items_required);
 
-  /* - Reads the number of input items from the tags using parse_length_tags()
+  /*!
+   * - Reads the number of input items from the tags using parse_length_tags()
    * - Checks there's enough data on the input and output buffers
    * - If not, inform the scheduler and do nothing
    * - Calls work() with the exact number of items per PDU
diff --git a/gr-blocks/include/blocks/tagged_stream_mux.h b/gr-blocks/include/blocks/tagged_stream_mux.h
index 23e8a94403..d271cf890f 100644
--- a/gr-blocks/include/blocks/tagged_stream_mux.h
+++ b/gr-blocks/include/blocks/tagged_stream_mux.h
@@ -31,12 +31,11 @@ namespace gr {
     /*!
      * \brief Combines tagged streams.
      *
-     * \description
      * Takes N streams as input.  Each stream is tagged with packet lengths.
      * Packets are output sequentially from each input stream.
      *
      * The output signal has a new length tag, which is the sum of all
-     * individual length tags.
+     * individual length tags. The old length tags are discarded.
      *
      * All other tags are propagated as expected, i.e. they stay associated
      * with the same input item.
@@ -48,7 +47,8 @@ namespace gr {
      public:
       typedef boost::shared_ptr<tagged_stream_mux> sptr;
 
-      /* \param itemsize Items size (number of bytes per item)
+      /*!
+       * \param itemsize Items size (number of bytes per item)
        * \param lengthtagname Length tag key
        */
       static sptr make(size_t itemsize, const std::string &lengthtagname);
diff --git a/gr-digital/include/digital/ofdm_frame_equalizer_vcvc.h b/gr-digital/include/digital/ofdm_frame_equalizer_vcvc.h
index d5d526ddc3..321c58473d 100644
--- a/gr-digital/include/digital/ofdm_frame_equalizer_vcvc.h
+++ b/gr-digital/include/digital/ofdm_frame_equalizer_vcvc.h
@@ -43,7 +43,7 @@ namespace gr {
      public:
       typedef boost::shared_ptr<ofdm_frame_equalizer_vcvc> sptr;
 
-      /*
+      /*!
        * \param equalizer The equalizer object that will do the actual work
        * \param len_tag_key Length tag key
        * \param propagate_channel_state If true, the channel state after the last symbol
diff --git a/gr-digital/include/digital/packet_header_default.h b/gr-digital/include/digital/packet_header_default.h
index a4158e728c..d69a0f30a6 100644
--- a/gr-digital/include/digital/packet_header_default.h
+++ b/gr-digital/include/digital/packet_header_default.h
@@ -30,9 +30,19 @@ namespace gr {
   namespace digital {
 
     /*!
-     * \brief <+description of block+>
+     * \brief Default header formatter for digital packet transmission.
      * \ingroup digital
      *
+     * For bursty/packetized digital transmission, packets are usually prepended
+     * with a packet header, containing the number of bytes etc.
+     * This class is not a block, but a tool to create these packet header.
+     *
+     * This is a default packet header (see header_formatter()) for a description
+     * on the header format). To create other header, derive packet header creator
+     * classes from this function.
+     *
+     * gr::digital::packet_headergenerator_bb uses header generators derived from
+     * this class to create packet headers from data streams.
      */
     class DIGITAL_API packet_header_default : public boost::enable_shared_from_this<gr::digital::packet_header_default>
     {
@@ -53,7 +63,8 @@ namespace gr {
       long header_len() { return d_header_len; };
       pmt::pmt_t len_tag_key() { return d_len_tag_key; };
 
-      /* \brief Encodes the header information in the given tags into bits and places them into \p out
+      /*!
+       * \brief Encodes the header information in the given tags into bits and places them into \p out
        *
        * Uses the following header format:
        * Bits 0-11: The packet length (what was stored in the tag with key \p len_tag_key)
@@ -70,7 +81,8 @@ namespace gr {
 	  const std::vector<gr_tag_t> &tags=std::vector<gr_tag_t>()
       );
 
-      /* \brief Inverse function to header_formatter().
+      /*!
+       * \brief Inverse function to header_formatter().
        *
        * Reads the bit stream in \in and writes a corresponding tag into \p tags.
        *
diff --git a/gr-digital/include/digital/packet_header_ofdm.h b/gr-digital/include/digital/packet_header_ofdm.h
index 6c3453ed1d..9f70900b49 100644
--- a/gr-digital/include/digital/packet_header_ofdm.h
+++ b/gr-digital/include/digital/packet_header_ofdm.h
@@ -48,7 +48,8 @@ namespace gr {
 		      int bits_per_sym=1);
       ~packet_header_ofdm();
 
-      /* \brief Inverse function to header_formatter().
+      /*!
+       * \brief Inverse function to header_formatter().
        *
        * Does the same as packet_header_default::header_parser(), but
        * adds another tag that stores the number of OFDM symbols in the
@@ -72,8 +73,8 @@ namespace gr {
 
      protected:
       pmt::pmt_t d_frame_len_tag_key;
-      const std::vector<std::vector<int> > d_occupied_carriers; //! Which carriers/symbols carry data
-      int d_syms_per_set; //! Helper variable: Total number of elements in d_occupied_carriers
+      const std::vector<std::vector<int> > d_occupied_carriers; //!< Which carriers/symbols carry data
+      int d_syms_per_set; //!< Helper variable: Total number of elements in d_occupied_carriers
     };
 
   } // namespace digital
diff --git a/gr-digital/lib/header_payload_demux_impl.h b/gr-digital/lib/header_payload_demux_impl.h
index ceab9a8629..dc8cc7883a 100644
--- a/gr-digital/lib/header_payload_demux_impl.h
+++ b/gr-digital/lib/header_payload_demux_impl.h
@@ -30,17 +30,17 @@ namespace gr {
     class header_payload_demux_impl : public header_payload_demux
     {
      private:
-      int d_header_len; //! Number of bytes per header
-      int d_items_per_symbol; //! Bytes per symbol
-      int d_gi; //! Bytes per guard interval
-      pmt::pmt_t d_len_tag_key; //! Key of length tag
-      pmt::pmt_t d_trigger_tag_key; //! Key of trigger tag (if used)
-      bool d_output_symbols; //! If true, output is symbols, not items
-      size_t d_itemsize; //! Bytes per item
-      bool d_uses_trigger_tag; //! If a trigger tag is used
-      int d_ninput_items_reqd; //! Helper for forecast()
-      int d_state; //! Current read state
-      int d_remaining_symbols; //! When in payload or header state, the number of symbols still to transmit
+      int d_header_len; //!< Number of bytes per header
+      int d_items_per_symbol; //!< Bytes per symbol
+      int d_gi; //!< Bytes per guard interval
+      pmt::pmt_t d_len_tag_key; //!< Key of length tag
+      pmt::pmt_t d_trigger_tag_key; //!< Key of trigger tag (if used)
+      bool d_output_symbols; //!< If true, output is symbols, not items
+      size_t d_itemsize; //!< Bytes per item
+      bool d_uses_trigger_tag; //!< If a trigger tag is used
+      int d_ninput_items_reqd; //!< Helper for forecast()
+      int d_state; //!< Current read state
+      int d_remaining_symbols; //!< When in payload or header state, the number of symbols still to transmit
 
       // Helpers to make the state machine more readable
 
diff --git a/gr-digital/lib/ofdm_frame_equalizer_vcvc_impl.h b/gr-digital/lib/ofdm_frame_equalizer_vcvc_impl.h
index cba2d513ea..ddfcc43694 100644
--- a/gr-digital/lib/ofdm_frame_equalizer_vcvc_impl.h
+++ b/gr-digital/lib/ofdm_frame_equalizer_vcvc_impl.h
@@ -36,7 +36,7 @@ namespace gr {
       std::vector<gr_complex> d_channel_state;
 
      protected:
-      // This aren't really necessary, so let's override them with nuthin'
+      // These aren't really necessary, so let's override them with nuthin'
       void remove_length_tags(const std::vector<std::vector<gr_tag_t> > &tags) {};
       void update_length_tags(int n_produced, int n_ports) {};
 
diff --git a/gr-digital/lib/ofdm_serializer_vcc_impl.h b/gr-digital/lib/ofdm_serializer_vcc_impl.h
index ef2f1c83b1..4f750eac71 100644
--- a/gr-digital/lib/ofdm_serializer_vcc_impl.h
+++ b/gr-digital/lib/ofdm_serializer_vcc_impl.h
@@ -30,16 +30,17 @@ namespace gr {
     class ofdm_serializer_vcc_impl : public ofdm_serializer_vcc
     {
      private:
-      int d_fft_len; //! FFT length
-      std::vector<std::vector<int> > d_occupied_carriers; //! Which carriers/symbols carry data
-      pmt::pmt_t d_packet_len_tag_key; //! Key of the length tag
-      pmt::pmt_t d_out_len_tag_key; //! Key of the length tag
-      const int d_symbols_skipped; //! Start position in d_occupied_carriers
-      int d_curr_set; //! Current position in d_occupied_carriers
+      int d_fft_len; //!< FFT length
+      std::vector<std::vector<int> > d_occupied_carriers; //!< Which carriers/symbols carry data
+      pmt::pmt_t d_packet_len_tag_key; //!< Key of the length tag
+      pmt::pmt_t d_out_len_tag_key; //!< Key of the length tag
+      const int d_symbols_skipped; //!< Start position in d_occupied_carriers
+      int d_curr_set; //!< Current position in d_occupied_carriers
       int d_symbols_per_set;
 
      protected:
-      /* Calculate the number of scalar complex symbols given a number of
+      /*!
+       * Calculate the number of scalar complex symbols given a number of
        * OFDM symbols.
        */
       int calculate_output_stream_length(const gr_vector_int &ninput_items);