Max and Pd (and probably sc but differently) - missing description of the output of a method

[tremblap]

This seems obvious now but it seems to have disappeared from our documentation.

For instance, in the ref, for fluid.knnclassifier, we don't say what message is coming our from a fittransform (etc) method invoqued. It was pointed to me byt one active learner now.

So I think in Max/Pd we should have an output description per method, describing the structure of the message coming out. For SC, maybe it should be part of the action function description (saying what we pass).

Thoughts?

[jamesb93]

We've never had output in the documentation AFAIK (at least not in Max).

Taking inspiration from the peek~ object the output section of the reference actually links back to the methods when you click the word int and float.

I'm not really sure how easy this is to achieve with our system though, but worst case scenario something that just describes the output would be sufficient IMO. Further, all of this should be situated in context of how useful this will be versus the time trade off to make docs produce it in a cross-platform way. The output section of the reference has no bearing on how one interacts or patches with the objects (i.e autocompletion) or outlet assistance. This is certainly the first time I've heard about the ref falling short in this manner so maybe people aren't looking at it much.

[tremblap]

There was one - it was in each method and at the top and very SC loaded.

The problem we have is that it is incomplete. We will find a way to make it complete. In the light of the new buffer interface, it got intermediate learner confused, so it is worth considering for sure. especially as it is not documented anywhere nor in the roll over of the outlets (which wouldn't fix SC)

We can talk. Documenting the output of a method seems quite important...

[tremblap]

peek is the wrong example - we need something that has multiple methods generating multiple types of output, which is where the confusion arises.

[jamesb93]

There was one - it was in each method and at the top and very SC loaded.

The presence of output in the .rst doesn't mean it was rendered from the template. Max AFAICT from the git log has never had the outputs denoted anywhere. There are many many many objects in Max that don't have their outputs written in the reference because they operate via convention (most jitter objects).

The problem we have is that it is incomplete. We will find a way to make it complete. In the light of the new buffer interface, it got intermediate learner confused, so it is worth considering for sure. especially as it is not documented anywhere nor in the roll over of the outlets (which wouldn't fix SC)

I don't disagree that the information could be more easily discovered by a user but it is not simple to just "put the output of a method" in the docs. This is not conventional and I think might overload people. For now, I think enough would be to have an output section that describes what the general principle is of the returns.

This would be enough to clarify what the output is and to indicate what is happening. That said, it is not universal so will require some moderate hacking at the templates and how information pertaining to outputs is differentiated between environments.

[tremblap]

I just don't know how it will work with the 'action' in SC but yes that is a solution. most objects have one type of output so they should be straingforward, but the whole dataset family has many output-triggering messages so that section will be a long one...

[jamesb93]

I just don't know how it will work with the 'action' in SC but yes that is a solution. most objects have one type of output so they should be straingforward, but the whole dataset family has many output-triggering messages so that section will be a long one...

They only have one type of output, which is a callback that is dependent on the input method. There are only three prototypes for this:

fittransform/fitpredict/fitencode
dump/clear/write/read
cols/size

Again, these message returns only behave in a meaningful way in Max (for chaining) whereas in SC you just have an action function that is essentially anonymous without any arguments... right?

[weefuzzy]

Not quite. Some messages actually return stuff (e.g. kNearest<Dist>, PCA::<fit>Transform, MLP::fit). All the Point messages have callbacks in SC that pass the output buffers as arguments

[jamesb93]

Not quite. Some messages actually return stuff (e.g. kNearest<Dist>, PCA::<fit>Transform, MLP::fit). All the Point messages have callbacks in SC that pass the output buffers as arguments

That's true of Max too, so another case to account for.