[import_functions] Improve header documentation

lib/import_functions.js

@@ -3,63 +3,58 @@
 ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////
 
 /*
-
+ * How to use this module?
-- First build a 'release' object that you'll fill in with your source of data
+ *
-
+ * - First build a release object (see expected format below) that you'll fill in from source of data
-- Call as follows, e.g.:
+ * - Call as follows, e.g.:
-
+ *     var parameters = MBReleaseImportHelper.buildFormParameters(parsedRelease, optionalEditNote);
-    var parameters = MBReleaseImportHelper.buildFormParameters( theParsedRelease, optionalEditNote );
+ * - Then build the HTML that you'll inject into source site page:
-
+ *     var formHtml = MBReleaseImportHelper.buildFormHTML(parameters);
-- Then build the HTML that you'll inject into source site page:
+ * - Addinionally, you can inject a search link to verify that the release is not already known by MusicBrainz:
-
+ *     var linkHtml = MBReleaseImportHelper.buildSearchLink(parsedRelease);
-    var formHtml = MBReleaseImportHelper.buildFormHTML( parameters );
+ *
-
+ * Expected format of release object:
-- Addinionally, you can inject a search link to verify that the release is not already known by MusicBrainz:
+ *
-
+ *     release = {
-    var linkHtml = MBReleaseImportHelper.buildSearchLink( theParsedRelease );
+ *         title,
-
+ *         artist_credit,
---- 'release' object format : ---
+ *         type,
-
+ *         status,
-    release = {
+ *         language,
-        title,
+ *         script,
-        artist_credit = [ { name: '',
+ *         packaging,
-        type,
+ *         country,
-        status,
+ *         year,
-        language,
+ *         month,
-        script,
+ *         day,
-        packaging,
+ *         labels = [ { name, mbid, catno }, ... ],
-        country,
+ *         barcode,
-        year,
+ *         urls = [ {url, link_type }, ... ],
-        month,
+ *         discs = [
-        day,
+ *             {
-        labels = [ { name, mbid, catno }, ... ],
+ *                 title,
-        barcode,
+ *                 format,
-        urls = [ {url, link_type }, ... ],
+ *                 tracks = [
-        discs = [
+ *                     { number, title, duration, artist_credit },
-            {
+ *                     ...
-                title,
+ *                 ]
-                format,
+ *             },
-                tracks = [
+ *             ...
-                    { number, title, duration, artist_credit },
+ *         ],
-                    ...
+ *     }
-                ]
+ *
-            },
+ *     where 'artist_credit' has the following format:
-            ...
+ *
-        ],
+ *     artist_credit = [
-    }
+ *         {
-
+ *             credited_name,
-    where 'artist_credit' has the following format:
+ *             artist_name,
-
+ *             artist_mbid,
-    artist_credit = [
+ *             joinphrase
-        {
+ *         },
-            credited_name,
+ *         ...
-            artist_name,
+ *     ]
-            artist_mbid,
+ *
-            joinphrase
-        },
-        ...
-    ]
-
  */
 
 var MBReleaseImportHelper = (function() {