Songpos Badly Documented

Renoise Tool Development
1

Looking at the docs, I see:

  
--------------------------------------------------------------------------------  
-- renoise.SongPos  
--------------------------------------------------------------------------------  
  
-------- properties  
  
-- Position in the pattern sequence.  
song_pos.sequence  
 -> [number]  
  
-- Pos in the pattern at the given pattern sequence.  
song_pos.line  
 -> [number]  
  
  
-------- operators  
  
==(song_pos, song_pos) -> [boolean]  
~=(song_pos, song_pos) -> [boolean]  
>(song_pos, song_pos) -> [boolean]  
>=(song_pos, song_pos) -> [boolean]  
 [boolean]  
<=(song_pos, song_pos) -> [boolean]

song_pos doesn’t exist?

2

Well, what i mean is:

  
local whatever = renoise.SongPos()  
print(whatever.sequence, whatever.line)

Where is song_pos? If it’s just a variable, it should be better documented.

It’s the only place in the documentation where an abstract variable, instead of something usable, is written. I was like “is this a constant? Or what?” when reading.

3

Well, but how?

Same thing applies to the ViewBuilder, Document, Socket and Midi class refs. Only renoise.app(), renoise.song() and renoise.tool() can provide full “working” instance descriptions, cause those are the only singletons in the API.

4

Hmmm, you are right. I didn’t notice it in ViewBuilder, for example.

I think the difference is that, in the ViewBuilder, you have something that looks like:

  
--------------------------------------------------------------------------------  
-- renoise.Views.View  
--------------------------------------------------------------------------------  
  
-- View is the base class for all following specialized views. All View   
-- properties can be applied to any of the following views.  
  
  
------ functions  
  
-- Dynamically create view hierarchies.  
view:add_child(View child_view)  
view:remove_child(View child_view)  
  
[...]

Where as the song_pos snippet just jumps directly into song_pos, with no foreword prefacing it.

I propose simply adding some padding / blah blah.

5

I propose simply adding some padding / blah blah.

I just ran into this same problem, and ended up at this thread after much Googling.

Perhaps the docs need a short example, or something that more clearly explains that renoise.song().transport.playback_pos returns a SongPos instance, and that instances of that kind have the such and such behavior. Which also suggests that this needs to come after transport has been explained.

1 Like
6

Yeah, that is a inducing way to document stuff.

Just get rid of the variable:

--------------------------------------------------------------------------------
-- renoise.SongPos
--------------------------------------------------------------------------------

-------- properties

-- Position in the pattern sequence.
sequence
-> [number]

-- Pos in the pattern at the given pattern sequence.
line
-> [number]

It won’t get clearer than this…

Or, if you insist on putting the reference to the object in there, then do it like this:

--------------------------------------------------------------------------------
-- renoise.SongPos
--------------------------------------------------------------------------------

-------- properties

-- Position in the pattern sequence.
renoise.SongPos().sequence
-> [number]

-- Pos in the pattern at the given pattern sequence.
renoise.SongPos().line
-> [number]

I also find the whole formatting very hard to read, but that is probably mainly due to Lua not having doctoring support in combination with a proper docstring to html reference tool.

7

Yeah, that is a inducing way to document stuff.
Just get rid of the variable:

--------------------------------------------------------------------------------
-- renoise.SongPos
--------------------------------------------------------------------------------

-------- properties

-- Position in the pattern sequence.
sequence
-> [number]

-- Pos in the pattern at the given pattern sequence.
line
-> [number]

It won’t get clearer than this…

Or, if you insist on putting the reference to the object in there, then do it like this:

--------------------------------------------------------------------------------
-- renoise.SongPos
--------------------------------------------------------------------------------

-------- properties

-- Position in the pattern sequence.
renoise.SongPos().sequence
-> [number]

-- Pos in the pattern at the given pattern sequence.
renoise.SongPos().line
-> [number]

That makes more sense.

I also find the whole formatting very hard to read, but that is probably mainly due to Lua not having doctoring support in combination with a proper docstring to html reference tool.

I’ve not tried this yet, but maybe useful: http://keplerproject.github.io/luadoc/

The reason I ran into this SongPos thing myself is because I find the docs just too clunky. Way back when I used to a lot of development with Microsoft tools, and the docs were almost always outstanding. Thinking about the various substructions of App, Document, Song, Track etc. reminded me of the docs for the Word object model. The dev docs provided a nice tree diagram, with clickable sections.

What I’ve been doing is reformatting the Renoise Lua docs into something of that ilk. By hand, which is tedious, until I can think out a good way to automate it. What I’m shooting for is at least to have a single file with assorted indentation to make it easier to see what things are related. For example, given a Track instance, what can I do with it.

The upside to the manual approach is I’m actually seeing, even if perhaps quickly, all the things available. But some thing, like SongPos, are confusing to follow.