MySQL Bugs: #40587: Doxygen documentation of backup image format is not up to date.

Bug #40587	Doxygen documentation of backup image format is not up to date.
Submitted:	8 Nov 2008 10:36	Modified:	25 Oct 2009 20:57
Reporter:	Rafal Somla	Email Updates:
Status:	Closed	Impact on me:	None
Category:	MySQL Server: Backup	Severity:	S3 (Non-critical)
Version:	6.0 source	OS:	Any
Assigned to:	Rafal Somla	CPU Architecture:	Any

Description:
The backup image format is documented in the source code of the backup stream library, in form of doxygen comments (files sql/backup/stream_v1*). However, the documentation is not complete and not up-to-date. There are differences between what is described in the documentation and what is implemented in the code. Also, some points are not clarified enough.

Fixing this is needed for writting a document describing backup image format in the internals manual.

How to repeat:
Read the code and documentation.

Here is a link to internals page documenting backup image format.

http://forge.mysql.com/wiki/MySQL_Internals_MySQL_Backup_Stream_API

A patch for this bug has been committed. After review, it may
be pushed to the relevant source trees for release in the next
version. You can access the patch from:

  http://lists.mysql.com/commits/81275

2863 Rafal Somla	2009-08-21
      Bug #40587 - Doxygen documentation of backup image format is not up to date
      
      This patch updates the doxygen documentation for the backup image format
      and fixes/clarifies issues found there. The format of the documentation is
      changed to the one which was proposed by Paul for the internals manual.
     @ sql/backup/kernel.cc
        - Add the main documentation page.
        - Include description of how to use kerenel API into doxygen docs.
     @ sql/backup/stream.cc
        - Add page describing general backup stream format used. Backup image format
          is described on a separate page.
     @ sql/backup/stream_v1.c
        Add pages describing general structure of image format v1 and the image layer
        format as implemented by functions in this file. Format of the image layer 
        documentation has been changed to the one proposed by Paul for the internals
        manual.
     @ sql/backup/stream_v1_transport.c
        Added pages documenting the transport layer format of a backup image. 
        Documentation format is changed to the one proposed by Paul for internals
        manual.

Patch approved pending satisfying minor required changes and acceptance by Paul that the patch meets his requirements.

A patch for this bug has been committed. After review, it may
be pushed to the relevant source trees for release in the next
version. You can access the patch from:

  http://lists.mysql.com/commits/82628

2868 Rafal Somla	2009-09-08
      Bug #40587 - Doxygen documentation of backup image format is not up to date
      
      This patch updates the doxygen documentation for the backup image format
      and fixes/clarifies issues found there. The format of the documentation is
      changed to the one which was proposed by Paul for the internals manual.
     @ sql/backup/kernel.cc
        - Add the main documentation page.
        - Include description of how to use kernel API into doxygen docs.
     @ sql/backup/stream.cc
        - Add page describing general backup stream format used. Backup image format
          is described on a separate page.
     @ sql/backup/stream_v1.c
        Add pages describing general structure of image format v1 and the image layer
        format as implemented by functions in this file. Format of the image layer 
        documentation has been changed to the one proposed by Paul for the internals
        manual.
        
        Also renamed bstream_rd_image_info() -> bstream_rd_snapshot_info() to follow
        new terminology and make it consistent with bstream_wr_snapshot_info().
     @ sql/backup/stream_v1_transport.c
        Added pages documenting the transport layer format of a backup image. 
        Documentation format is changed to the one proposed by Paul for internals
        manual.

A patch for this bug has been committed. After review, it may
be pushed to the relevant source trees for release in the next
version. You can access the patch from:

  http://lists.mysql.com/commits/82632

2869 Rafal Somla	2009-09-08
      Followup patch for BUG#40587. It moves definitions of functions 
      bstream_{rd,wr}_summary() in backup/stream_v1.c so that they are
      defined at the place where summary block format is described in
      the documentation. This is so that it is easy to verify that 
      functions correctly implement the described format.

A patch for this bug has been committed. After review, it may
be pushed to the relevant source trees for release in the next
version. You can access the patch from:

  http://lists.mysql.com/commits/82633

2869 Rafal Somla	2009-09-08
      Followup patch for BUG#40587. It moves definitions of functions 
      bstream_{rd,wr}_summary() and bstream_{rd,wr}_binlog_pos() in 
      backup/stream_v1.c so that they are defined at the place where 
      summary block format is described in the documentation. This is 
      so that it is easy to verify that functions correctly implement 
      the described format.

A patch for this bug has been committed. After review, it may
be pushed to the relevant source trees for release in the next
version. You can access the patch from:

  http://lists.mysql.com/commits/82651

2868 Rafal Somla	2009-09-08
      Bug #40587 - Doxygen documentation of backup image format is not up to date
      
      This patch updates the doxygen documentation for the backup image format
      and fixes/clarifies issues found there. The format of the documentation is
      changed to the one which was proposed by Paul for the internals manual.
     @ sql/backup/kernel.cc
        - Add the main documentation page.
        - Include description of how to use kernel API into doxygen docs.
     @ sql/backup/stream.cc
        - Add page describing general backup stream format used. Backup image format
          is described on a separate page.
     @ sql/backup/stream_v1.c
        Add pages describing general structure of image format v1 and the image layer
        format as implemented by functions in this file. Format of the image layer 
        documentation has been changed to the one proposed by Paul for the internals
        manual.
        
        Also renamed bstream_rd_image_info() -> bstream_rd_snapshot_info() to follow
        new terminology and make it consistent with bstream_wr_snapshot_info().
     @ sql/backup/stream_v1_transport.c
        Added pages documenting the transport layer format of a backup image. 
        Documentation format is changed to the one proposed by Paul for internals
        manual.

A patch for this bug has been committed. After review, it may
be pushed to the relevant source trees for release in the next
version. You can access the patch from:

  http://lists.mysql.com/commits/82655

2869 Rafal Somla	2009-09-08
      Followup patch for BUG#40587. It moves definitions of functions
      bstream_{rd,wr}_summary(), bstream_{rd,wr}_binlog_pos() and 
      bstream_{rd,wr}_item_pos() in backup/stream_v1.c so that they 
      are defined at the place where the format of the corresponding
      part of backup image is documented. This is so that it is easy 
      to verify that functions correctly implement the described format.

A patch for this bug has been committed. After review, it may
be pushed to the relevant source trees for release in the next
version. You can access the patch from:

  http://lists.mysql.com/commits/82659

2870 Rafal Somla	2009-09-08
      Followup patch for BUG#40587. It removes from bstream library code 
      which was supposed to handle aspects of backup image which were 
      never needed/used and disappeared from image format specifications.
      These are:
      
      1. The possibility of having the summary block inside image's preamble 
      instead of always having it at the end of the image. Current code 
      always writes summary at the end of backup image.
      
      2. Explicit listing of per-table objects in the catalogue and in the 
      metadata section. We do not handle per-table objects explicitly.
      Things like indexes are created together with the tables with one 
      CREATE TABLE statement.
     @ client/backup_stream.c
        Remove parts related to per-table iterator.
     @ client/mysqlbackup.cc
        Remove support for inline summary.
     @ mysql-test/suite/backup/t/backup_client_coverage.test
        Remove error injection which was testing per-table iterator code.
     @ sql/backup/kernel.cc
        Remove implementation of per-table iterator.
     @ sql/backup/stream_v1.c
        - Remove support for inline summary.
        - Remove code for writing/reading per-table objects.
     @ sql/backup/stream_v1.h
        - Remove BSTREAM_FLAG_INLINE_SUMMARY.
        - Remove structure for describing per-table objects.
     @ unittest/backup/bstr_callback_errors-t.c
        Remove test for per-table iterators.
     @ unittest/backup/catalog.c
        Remove implementation of per-table iterator.

A patch for this bug has been committed. After review, it may
be pushed to the relevant source trees for release in the next
version. You can access the patch from:

  http://lists.mysql.com/commits/82884

2869 Rafal Somla	2009-09-10
      Follow-up patch for BUG#40587. It moves definitions of functions
      bstream_{rd,wr}_summary(), bstream_{rd,wr}_binlog_pos() and 
      bstream_{rd,wr}_item_pos() in backup/stream_v1.c so that they 
      are defined at the place where the format of the corresponding
      part of backup image is documented. This is so that it is easy 
      to verify that functions correctly implement the described format.
     @ sql/backup/stream_v1.c
        - Remove support for inline summary.
        - Remove code for writing/reading per-table objects.

A patch for this bug has been committed. After review, it may
be pushed to the relevant source trees for release in the next
version. You can access the patch from:

  http://lists.mysql.com/commits/82885

2870 Rafal Somla	2009-09-10
      Follow-up patch for BUG#40587. It removes from bstream library code 
      which was supposed to handle aspects of backup image which were 
      never needed/used and disappeared from image format specifications.
      These are:
      
      1. The possibility of having the summary block inside image's preamble 
         instead of always having it at the end of the image. Current code 
         always writes summary at the end of backup image.
      
      2. Explicit listing of per-table objects in the catalogue and in the 
         metadata section. We do not handle per-table objects explicitly.
         Things like indexes are created together with the tables with one 
         CREATE TABLE statement.
     @ client/backup_stream.c
        Remove parts related to per-table iterator.
     @ client/mysqlbackup.cc
        Remove support for inline summary.
     @ mysql-test/suite/backup/t/backup_client_coverage.test
        Remove error injection which was testing per-table iterator code.
     @ sql/backup/kernel.cc
        Remove implementation of per-table iterator.
     @ sql/backup/stream_v1.c
        - Remove support for inline summary.
        - Remove code for writing/reading per-table objects.
     @ sql/backup/stream_v1.h
        - Remove BSTREAM_FLAG_INLINE_SUMMARY.
        - Remove structure for describing per-table objects.
     @ unittest/backup/bstr_callback_errors-t.c
        Remove test for per-table iterators.
     @ unittest/backup/catalog.c
        Remove implementation of per-table iterator.

A patch for this bug has been committed. After review, it may
be pushed to the relevant source trees for release in the next
version. You can access the patch from:

  http://lists.mysql.com/commits/82886

2871 Rafal Somla	2009-09-10
      Follow-up patch for BUG#40587. Fix the "metadata" word which was removed 
      by mistake in the original patch.

Pushed into 6.0-backup tree.
revision-id: rafal.somla@sun.com-20090908092908-t82h1nbcoox7o2r1

Pushed into 6.0.14-alpha (revid:alik@sun.com-20091025133616-ca4inerav4vpdnaz) (version source revid:ingo.struewing@sun.com-20090921175031-i1ubh1ln575lh1di) (merge vers: 6.0.14-alpha) (pib:13)

No changelog entry needed.