Incomplete API documentation: sample_mappings[]

It seems that all the documentation concerning the sample_mapping[] is incomplete.

Within sample_mapping[] there is another table that does not appear in the documentation, and which refers to the sample index.

For example, to access the note_range
rprint(renoise.song().selected_instrument.sample_mappings[1][1].note_range)

In the documentation it should be something like this, I guess:

-- Note range the mapping is triggered for.
renoise.song().instruments[].sample_mappings[].samples[].note_range, _observable 

--and

renoise.song().instruments[].sample_mappings[]:sample().note_range, _observable 

  -> [table with two numbers (0-119, c-4=48)]

.samples[] maybe? The same with the rest of properties…

Related documentation:

Renoise.Song.API.lua

--------------------------------------------------------------------------------
-- renoise.SampleMapping
--------------------------------------------------------------------------------

-- General remarks: Sample mappings of sliced samples are read-only: can not be
-- modified. See `sample_mappings[].read_only`

-------- Properties

-- True for sliced instruments. No sample mapping properties are allowed to 
-- be modified, but can be read.
renoise.song().instruments[].sample_mappings[].read_only
  -> [read-only, boolean]
  
-- Linked sample.
renoise.song().instruments[].sample_mappings[].sample
  -> [renoise.Sample object]

-- Mapping's layer (triggered via Note-Ons or Note-Offs?).
renoise.song().instruments[].sample_mappings[].layer, _observable
  -> [enum = renoise.Instrument.LAYER]

-- Mappings velocity->volume and key->pitch options.
renoise.song().instruments[].sample_mappings[].map_velocity_to_volume, _observable 
  -> [boolean]
renoise.song().instruments[].sample_mappings[].map_key_to_pitch, _observable 
  -> [boolean]

-- Mappings base-note. Final pitch of the played sample is:
--   played_note - mapping.base_note + sample.transpose + sample.finetune
renoise.song().instruments[].sample_mappings[].base_note, _observable 
  -> [number (0-119, c-4=48)]

-- Note range the mapping is triggered for.
renoise.song().instruments[].sample_mappings[].note_range, _observable 
  -> [table with two numbers (0-119, c-4=48)]

-- Velocity range the mapping is triggered for.
renoise.song().instruments[].sample_mappings[].velocity_range, _observable 
  -> [table with two numbers (0-127)]

Am I doing something wrong or is the documentation really incomplete?

Can anyone verify this? Please!

Ok, sample_mapping(layer, index) has two items, the “layer” and the “index” of the sample, which can never be worth 0, otherwise it will return an error.

-- Access to a sample mapping by index. Use property 'sample_mappings' to
-- iterate over all sample mappings and to query the sample (mapping) count.
renoise.song().instruments[]:sample_mapping(layer, index)
  -> [renoise.SampleMapping object]

For some reason I made a mess with this documentation. Maybe it should be better explained…

Maybe the following should be better explained:

-- Keyboard Note/velocity mapping
renoise.song().instruments[].samples[].sample_mapping
  -> [read-only, renoise.SampleMapping object]

If the sample exists, with: oprint(renoise.song().selected_sample.sample_mapping)

class: SampleMapping
 properties:
    base_note
    base_note_observable
    layer
    layer_observable
    map_key_to_pitch
    map_key_to_pitch_observable
    map_velocity_to_volume
    map_velocity_to_volume_observable
    note_range
    note_range_observable
    read_only
    sample
    velocity_range
    velocity_range_observable
 methods:
    __STRICT

Therefore, we have direct access to all properties, which is what we should all use:

renoise.song().instruments[].samples[].sample_mapping.base_note
renoise.song().instruments[].samples[].sample_mapping.layer
renoise.song().instruments[].samples[].sample_mapping.map_key_to_pitch
renoise.song().instruments[].samples[].sample_mapping.map_velocity_to_volume
renoise.song().instruments[].samples[].sample_mapping.note_range
renoise.song().instruments[].samples[].sample_mapping.read_only
renoise.song().instruments[].samples[].sample_mapping.sample
renoise.song().instruments[].samples[].sample_mapping.velocity_range

Specifically in this way:

renoise.song():instrument(ins_idx):sample(sam_idx).sample_mapping.base_note
renoise.song():instrument(ins_idx):sample(sam_idx).sample_mapping.layer
--...
--or
renoise.song().selected_sample.sample_mapping.base_note
renoise.song().selected_sample.sample_mapping.layer
--...

Since all this code is not shown in the documentation (it is something that the programmer must find by investigating), it is possible that the not very expert programmers end up using this, (that is much slower):

--------------------------------------------------------------------------------
-- renoise.SampleMapping
--------------------------------------------------------------------------------

-- General remarks: Sample mappings of sliced samples are read-only: can not be
-- modified. See `sample_mappings[].read_only`

-------- Properties

-- True for sliced instruments. No sample mapping properties are allowed to 
-- be modified, but can be read.
renoise.song().instruments[].sample_mappings[].read_only
  -> [read-only, boolean]
  
-- Linked sample.
renoise.song().instruments[].sample_mappings[].sample
  -> [renoise.Sample object]

-- Mapping's layer (triggered via Note-Ons or Note-Offs?).
renoise.song().instruments[].sample_mappings[].layer, _observable
  -> [enum = renoise.Instrument.LAYER]

-- Mappings velocity->volume and key->pitch options.
renoise.song().instruments[].sample_mappings[].map_velocity_to_volume, _observable 
  -> [boolean]
renoise.song().instruments[].sample_mappings[].map_key_to_pitch, _observable 
  -> [boolean]

-- Mappings base-note. Final pitch of the played sample is:
--   played_note - mapping.base_note + sample.transpose + sample.finetune
renoise.song().instruments[].sample_mappings[].base_note, _observable 
  -> [number (0-119, c-4=48)]

-- Note range the mapping is triggered for.
renoise.song().instruments[].sample_mappings[].note_range, _observable 
  -> [table with two numbers (0-119, c-4=48)]

-- Velocity range the mapping is triggered for.
renoise.song().instruments[].sample_mappings[].velocity_range, _observable 
  -> [table with two numbers (0-127)]

…if they discover how to use it.