Updated smnp.music (markdown)

smnp.music.md

@@ -2,6 +2,7 @@
 ## `noteFromInt(intPitch: int, duration: int, dot: bool)`
 Creates a note with given duration (including or not the dot) basing on passed `intRepr` value. The `intRepr` is a number representation of note's octave and pitch. It is computed using following algorithm:
 1. map available pitches to `integer`:
+```
         C ⇒ 0
         C# ⇒ 1
         D ⇒ 2
@@ -14,6 +15,7 @@ Creates a note with given duration (including or not the dot) basing on passed `
         A ⇒ 9
         A# ⇒ 10
         H ⇒ 11
+```
 2. convert a note's pitch value using mappings above
 3. multiple note's octave by 12 and add it to the result of the second point
 
@@ -31,10 +33,10 @@ Note, that the `intRepr` depends only on pitch and octave. Note duration doesn't
 ## `noteFromInt(intPitch: int, numerator: int, denominator: int)`
 Works similarly to `noteFromInt(intPitch: int, duration: int, dot: bool)`, however instead of determining note duration on `duration` and `dot` values, it enables you to provide a fully qualified duration as a fraction.
 
-Find out more about it at the description of [smnp.lang::Note](https://github.com/bartlomiej-pluta/smnp/wiki/smnp.lang#notepitch-string-octave-int-durationnumerator-int-durationdenominator-int) constructor.
+See [smnp.lang::Note](https://github.com/bartlomiej-pluta/smnp/wiki/smnp.lang#notepitch-string-octave-int-durationnumerator-int-durationdenominator-int) to find out more.
 
 ## `range(begin: note, end: note, filter: string = "all", duration: int = 4, dot: bool = false)`
-Returns a list contained of notes from begin (inclusive) to end (exclusive) with given duration (and optional dot).
+Returns a list contained of notes from begin (inclusive) to end (inclusive) with given duration (and optional dot).
 
 This function also allows you to filter output notes using one of following values as a `filter` argument:
 * `diatonic` - returns only diatonic notes (C, D, E, ...)
@@ -49,19 +51,74 @@ println(range(@d5, @a5, "chromatic") == [@d#5, @f#5, @g#5]);
 ```
 
 ## `transpose(value: int, ...notes: <note, int, string>)`
+Transposes provided notes by given value which is a number of semitones. Integers and strings are ignored.
 
 ## `transpose(value: int, notes: list<note, int, string>)`
-## `triplet(a: note, b: note, c: note)`
-## `quintuplet(a: note, b: note, c: note, d: note, e: note)`
+Transposes provided notes by given value which is a number of semitones. Integers and strings are ignored.
+
 ## `tuplet(sub: int, ...notes: note)`
+Returns given tuplet of provided notes as list.
+The `sub` argument determines how many notes are supposed to be replaced by the tuplet at the regular measure.
+For example, for:
+* _triplet_: 3 notes replace 2, so the `sub = 2`
+* _quintuplet_: 5 notes replace 4, so the `sub = 4`
+
+```
+triplet = tuplet(2, @c, @d, @e);
+quintuplet = tuplet(4, @c, @d, @e, @f, @g);
+```
+
+## `triplet(a: note, b: note, c: note)`
+Returns `tuplet(2, a, b, c)`.
+
+## `quintuplet(a: note, b: note, c: note, d: note, e: note)`
+Returns `tuplet(4, a, b, c, d, e)`.
+
 ## `semitones(...notes: <note, int, string>)`
 ## `semitones(staff: list<note, int, string>)`
+Returns a list of numbers of semitones between provided notes. The list is initially filtered against integers and strings, so the input list should have at least 2 notes.
+
+### Example
+```
+a = semitones(@c, @g);
+b = semitones(@c, @d, @e, @f);
+c = semitones([@c, @g]);
+d = semitones([@c, @d, @e, @f]);
+e = semitones([@c, 2, 4, @g]);
+
+println(a); # [7]
+println(b); # [2, 2, 1]
+println(c); # [7]
+println(d); # [[2, 2, 1]]
+println(e); # [7]
+```
+
 ## `transposeTo(target: note, ...notes: <note, int, string>)`
 ## `transposeTo(target: note, staff: list<note, int, string>)`
+Transposes provided notes to given target, so that the first of transposed notes will be equal to target. Integers and strings are ignored.
+
+### Example
+```
+cMajorScale = range(@c, @c5, "diatonic");
+aMajorScale = transposeTo(@a, cMajorScale);
+d5MajorScale = transposeTo(@d5, aMajorScale);
+
+println(aMajorScale == [@a, @h, @c#5, @d5, @e5, @f#5, @g#5, @a5]);      # true
+println(d5MajorScale == [@d5, @e5, @f#5, @g5, @a5, @h5, @c#6, @d6]);    # true
+```
 
 # Methods
 ## `note.withOctave(octave: int)`
+Returns a copy of the note with given octave.
+
 ## `note.withDuration(duration: int)`
+Returns a copy of the note with given duration.
+
 ## `note.withDuration(numerator: int, denominator: int)`
+Returns a copy of the note with given fully qualified duration (see [smnp.lang::Note](https://github.com/bartlomiej-pluta/smnp/wiki/smnp.lang#notepitch-string-octave-int-durationnumerator-int-durationdenominator-int) to find out more).
+
 ## `note.transpose(value: int)`
-## `note.toInt()`
+Returns a transposed by given value copy of the note.
+
+## `note.toInt()`
+Returns string representation of the note.