Documenting Code

//=========================================================================//! @function    TerrainChunkNode::QueueForRendering//! @brief       Add the terrain chunk to the render queue//!              //! @param       queue [in]	Render queue to add the chunk to//!              //=========================================================================void TerrainChunkNode::QueueForRendering ( Renderer::RenderQueue& queue )

/** * Bubble Sort, don't use. * @param array Integer array to have bubble sorted. * @param size Size of the array in memory. */void bubblesort( int * array, int size ){  /* Iterate through the neccessary elements in the array. */    /* Iterate through the remaining elements of the arrary. */      /* Compare the two elements to see which is smaller. */        /* Switch the elements so the smaller appears first. */}

/** * Bubble Sort, don't use. * @param array Integer array to have bubble sorted. * @param size Size of the array in memory. */void bubblesort( int * array, int size ){  int x, y, t;  /* Iterate through the neccessary elements in the array. */  for ( y=0; y<(size-1); y++ )  {    /* Iterate through the remaining elements of the arrary. */    for ( x=y+1; x<size; x++ )    {      /* Compare the two elements to see which is smaller. */      if ( array[x] < array[y] )      {        /* Switch the elements so the smaller appears first. */        t = array[x];        array[x] = array[y];        array[y] = t'      }    }  }}

void bubblesort( int * array, int size ){    const int * begin = array;    const int * end   = array + size;    for ( int * left_sortee = begin ; left_sortee != (end - 1) ; ++left_sortee )    {        for ( int * right_sortee = (left_sortee + 1) ; right_sortee != end ; ++right_sortee )        {             if ( *left_sortee > *right_sortee )             {                 std::swap( *left_sortee , *right_sortee );             }        }    }}

//// First, how it would look with really bad "how" comments ////// check if we're at the end of the inputif ( in_it == in_it_end ) {     // report the error     throw std::runtime_error("Corrupted Data [H Length]");}// read the lengthunsigned char len = *in_it++;// check if we're at the end of the inputif ( in_it == in_it_end ) {    // report the error    throw std::runtime_error("Corrupted Data [H Offset]");}// Read the offsetunsigned short offset = static_cast<unsigned char>(*in_it++);offset <<= 4; // shift offset right 4 bits offset |= (len>>4)&0x0F; // set low 4 bits of offet to high 4 bits of lenlen &= 0xF; // use only lowest 4 bits of lenlen += 2; // increment len by 2

//// It's real form with much better "what" comments ////// Read the length and offset of the match in the sliding window/* These are stored in 2 bytes, with the lower 4 bits of the first byte * being the length ( 0-15, representing 2-17 because there are no * 0- or 1-length matches ), the upper 4 bits of the first being * the lower order bits of the offset and the second byte being the * higher order bits of the offset. */if ( in_it == in_it_end ) {     throw std::runtime_error("Corrupted Data [H Length]");}unsigned char len = *in_it++;if ( in_it == in_it_end ) {    throw std::runtime_error("Corrupted Data [H Offset]");}unsigned short offset = static_cast<unsigned char>(*in_it++);offset <<= 4;offset |= (len>>4)&0x0F;len &= 0xF;len += 2;