Add porting guide for 1.5.0

CHANGELOG.md

@@ -20,7 +20,7 @@ As there have been additions to the libFLAC interfaces, the libFLAC version numb
 	* Built-in help and tool documentation are improved (H2Swine)
 	* When re-encoding a FLAC file from an existing FLAC file, a check is added that the MD5 sums of both files are the same
 * libFLAC and libFLAC++
-	* The library interfaces have been extended. See the porting guide ***TODO TODO TODO***
+	* The library interfaces have been extended. See the porting guide (part of the API documentation)
 	* An error is sent when a frame is missing
 	* The algorithm of the 'loose mid side' option has changed. Instead of checking every few frames which option is best and keeping that for the next few frames, a fast heuristic is now used. This was necessary to enable multithreading
 	* Most level 0 metadata interface functions now also work with Ogg FLAC files

include/FLAC/all.h

@@ -436,6 +436,51 @@
  *
  */
 
+/** \defgroup porting_1_4_3_to_1_5_0 Porting from FLAC 1.4.3 to 1.5.0
+ *  \ingroup porting
+ *
+ *  \brief
+ *  This module describes porting from FLAC 1.4.3 to FLAC 1.5.0.
+ *
+ * \section porting_1_4_3_to_1_5_0_summary Summary
+ *
+ * Between FLAC 1.4.3 and FLAC 1.5.0, there have been changes to
+ * existing functions and enums:
+ * - the functions FLAC__metadata_get_streaminfo,
+ *   FLAC__metadata_get_tags and FLAC__metadata_get_cuesheet can now
+ *   read from Ogg FLAC files
+ * - when encoding Ogg FLAC files, the 'samples' argument of the
+ *   write callback no longer always returns 0.
+ * - two error statuses have been added to the
+ *   FLAC__StreamDecoderErrorStatus enum
+ * - one status is added to FLAC__StreamDecoderState, which is only
+ *   used when the new decoding of chained streams functionality is
+ *   enabled
+ * - one status is added to FLAC__StreamDecoderReadStatus, which is
+ *   only used when the new decoding of chained streams functionality
+ *   is enabled
+ * - the function
+ *   FLAC__metadata_chain_write_with_callbacks_and_tempfile can now
+ *   be used regardless of whether a tempfile is actually needed,
+ *   which is useful when writing to a new file is desired anyway
+ *
+ * Furthermore, there have been the following additions:
+ * - the functions FLAC__stream_decoder_set_decode_chained_stream,
+ *   FLAC__stream_decoder_get_decode_chained_stream,
+ *   FLAC__stream_decoder_finish_link,
+ *   FLAC__stream_decoder_skip_single_link,
+ *   FLAC__stream_decoder_process_until_end_of_link and
+ *   FLAC__stream_decoder_get_link_lengths have been added
+ *   to support decoding of chained streams
+ * - the function FLAC__metadata_chain_write_new_file has been added,
+ *   which is useful to combine copying of a file with changing its
+ *   metadata
+ * - the function FLAC__stream_decoder_find_total_samples was added,
+ *   which seeks to the end of a file to find the total number of
+ *   samples
+ *
+ */
+
 /** \defgroup flac FLAC C API
  *
  * The FLAC C API is the interface to libFLAC, a set of structures