Add usage notes to README and update names in API

README.adoc

@@ -1,7 +1,27 @@
 = M3uParser
 
-M3uParser provides Java API around an M3U playlist.
+M3uParser provides Java API around an (extended) M3U playlist. Based on ANTLR grammar.
 
 image:https://api.bintray.com/packages/krom/maven/m3uparser/images/download.svg["Download", link="https://bintray.com/krom/maven/m3uparser/_latestVersion"]
 image:https://travis-ci.org/kromkrom/m3uparser.svg?branch=master["Build Status", link="https://travis-ci.org/kromkrom/m3uparser"]
-image:https://api.codeclimate.com/v1/badges/7a0a58d5015b63a63dce/maintainability["Maintainability", link="https://codeclimate.com/github/kromkrom/m3uparser/maintainability"]
+image:https://api.codeclimate.com/v1/badges/7a0a58d5015b63a63dce/maintainability["Maintainability", link="https://codeclimate.com/github/kromkrom/m3uparser/maintainability"]
+
+== Usage
+Public API consists of: `DefaultM3uParser` which implements `M3uParserWrapper` and `PlaylistEntry`.
+
+`getPlaylistProperties()` returns a map of properties from `#EXTM3U` section.
+
+`getPlaylistEntries()` return a list of playlist entries, each represented by `PlaylistEntry` class.
+Its members are:
+
+* `title` -- an entry title,
+* `path` -- a path or a URL of a file,
+* `length` -- file length (commonly -1 or 0 for streams),
+* `group` -- group name from `#EXTGRP` (could be `null`),
+* `properties` -- a map of entry-specific properties from `#EXTINF` section.
+
+== Format specification
+There is no formal specification for M3U format (see https://en.wikipedia.org/wiki/M3U).
+
+M3uParser supports "extended M3U", in particular `\#EXTM3U`, `#EXTINF` and `#EXTGRP` directives.
+All other comments (starting with `#`) are ignored.

src/main/kotlin/ru/grushetsky/m3uparser/DefaultM3uParser.kt

@@ -11,7 +11,7 @@ class DefaultM3uParser(input: String) : M3uParserWrapper {
         parser = M3uParser(CommonTokenStream(m3uLexer))
     }
 
-    override fun getPlaylistParameters(): Map<String, String> {
+    override fun getPlaylistProperties(): Map<String, String> {
         return createParameterMap(parser.file().file_header().parameters().parameter())
     }
 

src/main/kotlin/ru/grushetsky/m3uparser/M3uParserWrapper.kt

@@ -1,6 +1,6 @@
 package ru.grushetsky.m3uparser
 
 interface M3uParserWrapper {
-    fun getPlaylistParameters(): Map<String, String>
+    fun getPlaylistProperties(): Map<String, String>
     fun getPlaylistEntries(): List<PlaylistEntry>
 }

src/main/kotlin/ru/grushetsky/m3uparser/PlaylistEntry.kt

@@ -1,9 +1,9 @@
 package ru.grushetsky.m3uparser
 
 data class PlaylistEntry(
-    val name: String,
+    val title: String,
     val path: String,
     val length: Int,
     val group: String?,
-    val parameters: Map<String, String>
+    val properties: Map<String, String>
 )