Documentation, documentation documentation...

Lindon

So its a really really cool tool. It's also really really frustrating..... I cannot seem to find any meaningful documentation. - Well what I found is really really incomplete.

Example:

So I want to do this in a panel

g.drawEllipse(var area, float lineThickness)

so the ApiCollection shows me this documentation...great! .BUT, ... whats an "area" its some object type I need to declare(probably some sort of x,y, height, width? maybe?)

..and area isnt documented anywhere I can find. Am I missing something fundamental, wheres the Class Hierarchy at least? I'm not looking for anything fancy - but this is a problem I come up against every single time I try to use HISE the ApiCollection may be complete but the documentation really really isnt.

As I say am I missing something here?

d.healey

I think we all agree that the documentation needs some work and even the built in API helper could have a little more clarity in some areas, is there any way we could help with this @Christoph-Hart? Perhaps have a publicly editable wiki?

Here is the explanation you need to draw a circle.

The area is an array that defines the x, y, width, and height of the shape.

Content.setHeight(250);

const var canvas = Content.addPanel("canvas", 0, 0);
canvas.set("height", 200);
canvas.set("width", 300);

canvas.setPaintRoutine(function(g)
{
	g.drawEllipse([0, 0, 100, 100], 0.5);
});

How did I come by this elusive info... it's all here on the forum but some of it is buried in threads and you have to dig to find it.

Lindon

Yeah I worked that out by:

Looking through Christoph's example Scripted Panel - so actually Im NOT looking for an answer to a specific question - I'm looking for a tool to use to answer several questions - several per day as it happens.

d.healey

Does this help you - http://hartinstruments.net/hise/api/annotated.html? I think this forum is the best help resource we have for now.

Lindon

Yes exactly. Thanks Dave.

Of course the first thing I look for is the Area object/class - and its not there - so either:

we need to add a Class called Area with all the associated methods for dealing with it - which in this case would seem to be massive overkill.
or
we need to stop referring to "Area" at all and say Array of: x,y,width,height

so the ApiCollection documentation for drawEllipse would need to change to :

drawEllipse(array[int x_start, int y_start, int width, int height], float LineThickness)

d.healey

Yes that would be clearer. What do you think about using a wiki?

Lindon

Absolutely in favour of using a wiki.. as long as Christoph is comfortable with that and then he can re-use the wiki definitions(once they settle down) in the on-board documentation

Christoph Hart

Actually, the ScriptPanel is one of the few things where there's a rather complete documentation:

(hise.audio)

But I agree with you that the documentation is lacking (and you're definitely not the first to say so). But there's just so many hours in the day and I am completely busy supervising projects and working on the codebase.

The current API browser is autogenerated from the source code and this is the only way how to keep it up to date. However this opposes some restrictions on the formatting so g.drawEllipse([x, y, w, h], thickness) would not work.

I don't know if a wiki is neccessary, because the existing documentation is fully available on GitHub and I am happy to accept pull requests from anyone that contributes something there - unlike the actual codebase you don't need to be a C++ wizard to help :)

d.healey

Ah that sounds like a good idea. I'll check out the documentation on GitHub

Lindon

The documentation on GitHub seems ot be pretty much a replication of the documentation on the web site. so:

Christoph Hart 28 minutes ago
Actually, the ScriptPanel is one of the few things where there's a rather complete documentation:

so I'm not sure this is the case. I count at least 21 methods when press ESC, and these are not all documented on the web site and thus GitHub. appreciate much of this is "documented" in the ApiCollection - but we clearly need more comprehensive documentation. that says (more) exactly:

++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
g.drawEllipse(var area,float lineThickness)
area = array of 4 values: [float x_pos, float y_pos, float width, float height]

example: g.drawEllipse([0,0,30,30],5)

++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

It's only a small change but its an accumulation of these that will make for usable documentation and better take up of the product I think.

d.healey

@Lindon Did you include this documentation too - http://hise.audio/manual/ScriptPanel.php?

Lindon

yep.

press esc and the first listed call is g.addDropShadowFromAlpha(int colour, int radius), cant see where thats documented on the page you reference.

and here:

http://hartinstruments.net/hise/api/annotated.html

Panel isnt even mentioned....

d.healey

Aha I see what you mean

Documentation, documentation documentation...

47

1.7k

11.7k

101.8k