continued the documentation of the programming interface

src/music_kraken/__init__.py

@@ -104,7 +104,6 @@ def cli(start_at: int = 0, only_lyrics: bool = False):
 
     if start_at <= 0:
         search = search_for_metadata()
-        # search = metadata.search.Option("release", "f8d4b24d-2c46-4e9c-8078-0c0f337c84dd", "Beautyfall")
         logging.info("Starting Downloading of metadata")
         metadata_downloader = metadata_fetch.MetadataDownloader()
         metadata_downloader.download({'type': search.type, 'id': search.id})

src/try-programming-interface.py

@@ -25,23 +25,91 @@ Or you can search with a text Querry like in the default cli:
  - Search.search_from_query(self, query: str)
 """
 
-multiple_objects = search_object.search_from_text(artist=input("input the name of the artist: "))
+multiple_options = search_object.search_from_text(artist=input("input the name of the artist: "))
 
 """
 both possible methods return an instance of MultipleOptions. It can just be
 printed or converted to a string.
 """
 
-print(multiple_objects)
+print(multiple_options)
 
 """
 After the first "text search" you can either again search again with the same function,
 or you can further explore one of the options from the previous search.
 For this simply call Search.choose(self, index: int).
-The index represents the number in the previously returned instance of MultipleOptions. Thus
+The index represents the number in the previously returned instance of MultipleOptions. 
-you **NEED TO BEFORHAND DO A "TEX SEARCH"**. Else it will not work.
+The element which has been chosen with `choose(i)` will be selectend,
+and can be downloaded with following steps
+
+Thus this has to be done **after either search_from_text or search_from_query**
 """
 
+# choosing the best matching band
+multiple_options = search_object.choose(0)
+# choosing the first ever release group of this band
+multiple_options = search_object.choose(1)
+# printing out the current options
+print(multiple_options)
+
+"""
+This process can be repeated indefenetly (until you run out of memory). 
+A search history is kept in the Search instance. You could go back to 
+the previous search like this:
+
+multiple_options = search.get_previous_options()
+"""
+
+# DOWNLOADING METADATA / FILLING UP THE CACHE DB
+
+"""
+If you selected the Option you want with `Search.choose(i)`, you can
+finally download the metadata of either:
+ - an artist (the whole discography)
+ - a release group
+ - a release
+ - a track/recording
+To download you need the selected Option Object (`music_kraken.metadata.metadata_search.Option`)
+it is simply stored in Search.current_option.
+
+If you already know what you wan't to download you can skip all the steps above and just create
+a dictionary like this and use it later (*might change and break after I add multiple metadata sources which I will*):
+```python
+{
+    'type': option_type,
+    'id': musicbrainz_id
+}
+```
+The option type is a string (I'm sorry for not making it an enum I know its a bad pratice), which can
+have following values:
+ - 'artist'
+ - 'release_group'
+ - 'release'
+ - 'recording'
+**PAY ATTENTION TO TYPOS, ITS CASE SENSITIVE**
+
+The musicbrainz id is just the id of the object from musicbrainz.
+"""
+
+# in this example I will choose the previous selected option.
+option_to_download = search_object.current_option
+print(option_to_download)
+
+"""
+If you got the Option instance you want to download, then downloading the metadata is really straight
+forward so I just show the code.
+"""
+
+# I am aware of abstrackt classes
+metadata_downloader = mk.metadata.metadata_fetch.MetadataDownloader()
+metadata_downloader.download({'type': option_to_download.type, 'id': option_to_download.id})
+
+"""
+This will add the requested songs to the cache database.
+"""
+
+
+# CACHE / TEMPORARY DATABASE
 """
 All the data can be gotten from the temporary database / cache.
 You can get the database object like this: