[Clam-devel] [Fwd: about CLAM audio]

[Pau Arumi]

En/na globot ha escrit:
> about documentation, to be honest the doxygen doc is like a cheese with 
> a lot of hole. You should think about people that don't know much about 
> sound (like me). So a small a synthetique explanation about each element 
> would be great. For example, i want to use a 3 band filter, there is an 
> input for controller named "Amount", i do not know what is it and can't 
> find a small explanation (so i have to experiment and loose time).
> this kind of example can be found a little evrywhere this is the 
> difficulty,

agree. documentation of each processing algorithm, port and control
is another open trench. actually we are going to make this doc
available from runtime. so for instance, networkeditor processing
tree will show the doc. this feature (related to plugins and
metadata) will appear very soon, and it will (hopefully) motivate
adding brief doc of most of the processings.

> Or in the OutControl class there is a SendControlAsBoolean method, and 
> the comment say "see comments on InControl.hxx about 
> InControl::GetLastValueAsBoolean" but i can not find this method...

aghh. that's old code written by rather inexperienced developers
(that's me 4 year ago ;) ). doc fixed now.

and while we where on it i've also completed the controls interface
(and doc) so it can have a real utility. also thorough unit tests
and have been added:

- existing:
   int OutControl::SendControlAsBoolean( bool booleanValue )
- new ones:
   int OutControl::SendControlAsBoolean( bool booleanValue )
   bool InControl::GetLastValueAsBoolean() const
   int InControl::GetLastValueAsInteger() const

commited on revision 10596

> something also very boring is that a doxygen doc don't allow search 
> easily (with a search box), so even if i prefer man pages, sometime i 
> like the conveniency of a big PDF  file (can be generated by doxy) with 
> extensive description of each class, method, var, enum ... because I can 
> search fast what i want to use.

adding a pdf its easy. will do on september (i've added a feature
request in the tracker)

> of course for people just using network editor extensive definition are 
> not needed, but in some case peoples might want to do thinks by hand 
> like getting pointers on controlers of a network to sendcontrols with 
> there interface and if i don't know what is a TControlData this might 
> seem difficult for some people.

i've also added a brief doxygen explanation about events (control)
type in InControl and OutControl classes. however, maybe we need a
how-to or other kind of docs to explain this basics.

btw, we plan to convert controls in typed connections (see pattern)
similar to current ports, so we can send structured info like midi
or osc.

> I know it is a little boring to explain evrythings, but it is usefull 
> for a lot of folks, and it is always better to writte the doc part at 
> the same time as the dev progress.

agree.
refactorings are also a good excuse to improve
documentation, and we do a lot of this lately...

> for the moment I don't have time to code the seeking and current time 
> reading, but if nobody do it in a few weeks i will be obliged to do it 
> :) (in fact no because it is not a key feature for my project, but i 
> want it).
> I don't know exactly when i will do it, i'll keep you informed. You can 
> add this task to the TODO list (or feature Requests).

the feature request has been added to the tracker.
whoever needs the feature first, roman, david, you... start
implementing it giving a notice to the list.

thanks for your feedback!
and don't be shy with patches (even for small details)  :)

pau