Hi Florian,
Extending the automatic documentation system is certainly possible, but
would require some extra work. Two other (easier) possibilities could be:
- use the same markdown convention that we use for the standard faust
libraries (see documentation/library.pdf/contributing page 15),
- declare your own metadata in the source code and process the json file
"foo.dsp.json" resulting from "faust -json foo.dsp".
Can you give an example of how you would like ideally to document your code?
Cheers
Yann
-------------------------
Yann Orlarey
Directeur scientifique
www.grame.fr
2017-06-14 16:41 GMT+02:00 Florian Grond <floriangr...@gmail.com>:
> Hello,
>
> A group of SuperCollider devs started discussing what a best practice for
> integrating Faust-based SuperCollider plugins should look like. One idea
> that came up was to automate SuperCollider helpfile generation inspired by
> the faust2mathdoc script.
>
> In a SuperCollider helpfile we would need to be able to document all the
> input arguments and also what the UGen returns. Now thinking outside the
> needs of SuperCollider, this would conform with documenting the inlets and
> outlets of MaxMSP or PureData and possibly similar needs on other platforms
> too.
>
> The documentation in chapter 11
> http://faust.grame.fr/images/faust-quick-reference.pdf
> lists 6 specific tags:
> mdoc, equation, diagram, metadata, notice, listing.
>
> None of them seems specifically dedicated to the arguments of the UGen or
> to what the UGen would return e.g. how many audio channels etc.
>
> Questions A) What tag do you suggest? Should a new specific tag be
> introduced? How can documentation be best autogenerated based on the Faust
> code, the wires and what process returns?
>
> Also, we think that the Faust code might possibly contain data structures
> that would be worth translating into Class variables of the SuperCollider
> language side representation the UGen.
> To give an example, I've used many times the Ambisonics decoder toolbox
> which generates Ambisonics decoders as dsp files based on MATLAB code.
> Here it would be fantastic if there was a way to document speaker
> positions in the .dsp file and to translate them into a class variable in
> SuperCollider. I imagine that there are other cases where similar needs
> exist.
>
> Question B) What would be the best way to achieve that? how could these
> types of data best be handled/documented so that it can be passed on to the
> documentation in other platforms?
>
> Florian
>
>
>
>
>
>
>
> ------------------------------------------------------------
> ------------------
> Check out the vibrant tech community on one of the world's most
> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
> _______________________________________________
> Faudiostream-users mailing list
> Faudiostream-users@lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/faudiostream-users
>
>
------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot
_______________________________________________
Faudiostream-users mailing list
Faudiostream-users@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/faudiostream-users
