On Thursday 09 April 2009 23:55:11 marius schebella wrote:
2009/4/9 Frank Barknecht fbar@footils.org:
Hallo,
dmotd hat gesagt: // dmotd wrote:
i am not at all convinced that pdpedia/mediawiki serves as a good method for object reference. it is difficult to maintain (a lot of manual copy and paste), its search/sort functionality is limited, the up/down stream api is severely lacking and most of all it is difficult to integrate it into a pd environment (outside of simple pddp links which are usually inside the object reference anyhow).
I believe, reference documentation belongs into the code and additional display methods should be generated from that.
hi frank, please be more elaborate. are you distinguishing between reference and documentation? is "reference documentation" the help patches or some other kind of object reference. are you talking about code comments? in help patches? or in the C code?
I think that the purpose of documentation is to teach/explain how to use objects? reference might be something slightly different.
the problem imho is that there is no basis right now on which an automatic documentation generation could build on. I also think that autogeneration would be extremely helpful, but... who of the vanilla/external-developers will reliably stick to any rules? since developers are bad documentators but you still propose that code should be the source to generate documentation, how do you think people (who would like to do some documentation) should contribute? directly to the source code?
how do you envision that users will search for objects? where do you think information like tags, similar objects, example patches should come from?
marius.
i'd love to see as much documentation, tags, categories, etc coming directly from the c code itself, heck.. why not even build a pd class library that stores all of this extraneous info internally! but really with the current codebase it is not feasible to make old objects adhere to some new documentation api subset, and unlikely that new object writers would adhere to that anyhow. that's why its important to make documenting pd as simple as possible and as straight forward as contributing to any wiki for text.
frank! your list-abs dynamic reference system is awesome.. that sort of thing should be encouraged everywhere, great job!
dmotd