One Doc Entry a Day Keeps the Forum Away

aaronventure

Inspired by the snippet waiting room post, I want to start a similar initiative for the docs. I think a lot of people would have something to say about various methods in the API but the process of both updating the doc files and creating a pull request is a bit convoluted.

At least that's my theory, and I'd like to put it to test here.

The idea is simple: we tackle one API category at a time. Every day, everyone makes an effort to write an example about one method in the category. Post what you know. Post about the kinks you found.

Once it's filled or once a week, @Christoph-Hart can go over it, pick the ones that seem to fit the bill best and update the docs. Snippets welcome, of course. Maybe these snippets can then be arranged into API topic-specific snippets that collect everything, but I'll leave that idea for later; right now let's just do code examples for the API.

If this persists, we should be able to cover the entire API by year's end.

Some formatting ideas:

Second level markdown heading for method names: ## Class.method()
Three underscores in the next line: ___
Single backticks for referring to methods or code bits in the description: `

If you decide to write an entry, it could be a good idea to create an empty post

Class.method()

so multiple people don't end up working on the same method. Once you're done, edit it and fill it out.

aaronventure

Starting with:

ARRAY

https://docs.hise.dev/scripting/scripting-api/array/index.html

clear - aaronventure OK
concat - aaronventure OK
clone - aaronventure
~~contains~~
~~find~~
~~indexOf~~
~~insert~~
isArray - aaronventure
~~join~~
map - aaronventure
pop - aaronventure
~~push~~
pushIfNotAlreadyThere - aaronventure
remove - aaronventure
removeElement - aaronventure
~~reserve~~
reverse - aaronventure
~~sort~~
sortNatural - aaronventure

aaronventure

Array.clear()

Clears the array.

Array.clear()

This is a quick operation (the allocated storage space will not be freed), so you can use it in a realtime callback.

const var arr = []; // Declare an array

for(i = 0; i < 10; i++)
{
	arr[i] = Math.randInt(0, 1000);
}
Console.print(trace(arr)); // [ 523, 5, 76, 345, 765, 45, 977, 223, 44, 54]

arr.clear();

Console.print(trace(arr)); // []

Christoph Hart

@aaronventure yup good idea. I'm going to pin this thread.

I'm not sure if every single method needs a code snippet (and some are really described fully by the autogenerated one liner), but filling out the gaps of the scripting API docs is on our immediate roadmap anyway (I'm currently going through the scriptnode list), so any help with that is definitely welcomed.

Another thing that could be helpful are simply requests for specific methods that are ridiculously under-documented - this would be the most low effort contribution one can make to the docs but it gives me the hint on what to prioritize because for me every API method is completely clear and the docs are unnecessary :)

aaronventure

@Christoph-Hart said in One Doc Entry a Day Keeps the Forum Away:

I'm not sure if every single method needs a code snippet (and some are really described fully by the autogenerated one liner), but filling out the gaps of the scripting API docs is on our immediate roadmap anyway (I'm currently going through the scriptnode list), so any help with that is definitely welcomed.

Yeah not every method needs it from the perspective of someone doing this for more than a couple of months, but if you just got here, reading the code example for the clear() method I posted also tells you:

ah, that's how you do a random integer
cool, the trace() method is how I convert anything to a string, I guess. Doesn't that have its own entry somewhere?

I'm working off of the KSP documentation example where almost every single method has:

a short description
detailed explanation of parameters
a real-life example
a link to related or relevant methods

https://www.native-instruments.com/ni-tech-manuals/ksp-manual/en/welcome-to-ksp

aaronventure

Array.concat()

Array.concat(var arrayList)

Concatenates (joins) two or more arrays. Ignores non-array argument elements.

var argumentList	A list of arrays. Ignores non-array elements. E.g. `arr1, arr2, [4, 5, 6], 7`

const var arr1 = [0, 1, [2, 3, 4]];
Console.print(arr1.length); // 3    // the array in the array is counted as a single element

const var arr2 = [5, 6, 7];
const var arr3 = [8, 9, 10];

arr1.concat(arr2);
Console.print(trace(arr1)); // [0, 1, [2, 3, 4], 5, 6, 7]

arr1.concat(arr3);
Console.print(trace(arr1)); // [0, 1, [2, 3, 4], 5, 6, 7, 8, 9, 10]     // the arr1 already contains arr2 

const var arr4 = []; // set type to array
arr4.concat(arr2, arr3, 8726, [11, 12, 13]);
Console.print(trace(arr4)); // [5, 6, 7, 8, 9, 10, 11, 12, 13]   // non-array arguments get ignored // arguments can be arrays themselves

Christoph Hart

I've pushed your suggestions and added the find method myself.

The only thing I had to change is the location of the comments:

descriptive comments that explain stuff go into a single line before the code line
Console outputs go at the end of the console.print line

This ensures that the most interesting bits are visible without having to scroll in the codebox.

BTW, with the Array API it might make sense to link to the docs of the official Javascript class and highlight differences (if there are any, I tried to stick as close as possible to the official API). For example the find method has this documentation:

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/find?retiredLocale=de

aaronventure

@Christoph-Hart Nice.

For concat(), the

// error: arr4 is not of type array

part was in there by mistake. Oops.

@Christoph-Hart said in One Doc Entry a Day Keeps the Forum Away:

This ensures that the most interesting bits are visible without having to scroll in the codebox.

Agree

@Christoph-Hart said in One Doc Entry a Day Keeps the Forum Away:

BTW, with the Array API it might make sense to link to the docs of the official Javascript class and highlight differences (if there are any, I tried to stick as close as possible to the official API). For example the find method has this documentation:

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/find?retiredLocale=de

Yeah. Same for the String class.

I would highlight in the Basic usage section that each array always has a length property that is written on compilation, and is accessible via array.length. Just to highlight that it's not a class method, but just accessing the property (is that how it's coded in the back? that's how I'm understanding it)

Christoph Hart

part was in there by mistake. Oops.

Yeah I was also confused by this, but I was too lazy trying to figure out what you meant with it. I'll remove it with the next batch.

aaronventure

Array.isArray()

Checks if the given variable is an array.

Array.isArray(var variableToTest)

A simple bool check whether the argument variable is of type array.

Call it on an array, or on the Array class object. If you call it on a non-array variable, the method won't be found and you'll get an error.

const var arr1 = 0;
const var arr2 = [];

var enableSomething = Array.isArray(arr2);
Console.print(enableSomething); // true

var enableSomethingElse = Array.isArray(arr1) && Array.isArray(arr2); 
Console.print(enableSomethingElse); // false

Console.print(arr1.isArray(arr1)); // Error: unknown function `isArray`

d.healey

@Christoph-Hart said in One Doc Entry a Day Keeps the Forum Away:

Another thing that could be helpful are simply requests for specific methods that are ridiculously under-documented

array.clone() && object.clone() - these, and a few other commands, don't show up in the API browser at all so you only know about them if you poke around in the source code or watch my videos :)

https://youtu.be/inpAs00hWHw

aaronventure

Array.pop()

Removes and returns the last element.

Array.pop()

This is useful for managing sequential input that you're keeping track of: history of played notes, velocities, custom undo history etc.

const arr1 = [1, 2, 3];
arr1[4] = 5;

Console.print(arr1.pop()); // 5

// we didn't set the 4th element (index 3) so it'll be undefined
Console.print(arr1.pop()); // error: API call with undefined parameter 

arr1[3] = 22;
Console.print(trace(arr1)); // [1, 2, 3, 22]

// we can check ourselves for errors in our logic in this case
if (isDefined(arr1.pop() 
{
    // do stuff
}

aaronventure

@d-healey post an entry

Christoph Hart

@aaronventure Lol what's the deal with Array.isArray()? It spits out the wrong value (zero) if I use it with an array and throws an error if it's not an array?

That's gotta be the least useful function in the entire API... I think I'll remove it altogether.

d.healey

@Christoph-Hart Works here - I think you guys are using it incorrectly.

Christoph Hart

@d-healey Ah, yeah I looked in the source code in order to remove it but that's exactly how it works, but then Aarons example is wrong.

I also noticed that there are a few gems that are not showing up in the API - Array.filter(), Array.some() etc. which are quite powerful functions. I'll investigate.

aaronventure

@Christoph-Hart ah fuck. Alright nice, we're already making progress and we're still on the warmup class!

The show starts when we finish with the Array class.

aaronventure

Array.reverse()

Reverses the order of the elements in the array.

Array.reverse()

_

const var arr1 = [1, 2, 3];
arr1.reverse();
Console.print(trace(arr1)); // [3, 2, 1]

aaronventure

Array.remove()

Removes all instances of the given element.

Array.remove(var elementToRemove)

const var arr1 = [1, 2, 3, 4, 2, 5,];
arr1.remove(2);

Console.print(trace(arr1)); // [1, 3, 4, 5]

aaronventure

Array.removeElement()

Removes the element at the given position.

Array.removeElement(int index)

const var arr1 = [1, 2, 3];
Console.print(arr1[1]); // 2

arr1.removeElement(1);
Console.print(arr1[1]); // 3

One Doc Entry a Day Keeps the Forum Away

Some formatting ideas:

Class.method()

ARRAY

Array.clear()

Array.concat()

Array.isArray()

Array.pop()

Array.reverse()

Array.remove()

Array.removeElement()

10

1.9k

10.7k

93.0k