Hi, sorry I've been a bit quiet for a bit! So I'm thinking of making up for it by spending some time improving the component reference docs in Kamaelia ( http://www.kamaelia.org/Components ). I've got a few questions:
First up: Any particular components that stand out to anyone as lacking documentation? I'm not promising to take any notice of anyone's suggestions, but I'll bear them in mind ;-) Next: Kamaelia.Apps contains a fair few components and prefabs. However, being app specific, I'm unsure if they're appropriate to "component reference" documentation. Should I bother doing these? Should I make reference to the apps to which they belong? Would documenting them just serve to confuse (since presumably they are of limited reusability, being app specific) Finally, a more complicated one: Some source files are completely undocumented, or appear confusingly sparse - particularly those that provide support or helper functions that are neither components nor prefabs. Eg. much of Kamaelia.Support. I'm thinking in some of those cases it may be useful to have documentation for those items. For example: Kamaelia.Visualisation.Axon.PComponent is a class that must be plugged into the topology visualiser to render blobs that visually represent kamaelia components. This already contains some helpful docstrings, but they don't make it into the reference docs. I see two possiblities at the moment: 1) Allow the docs to include these things - since they're useful. 2) Leave things as they stand, because this is a "component reference" and they are not components. My gut feeling is that (2) might be favouring purity over usefulness; however would (1) necessitate changing the name from "component reference" to something else to avoid confusion? If we plump for (1) then I'd propose implementing it by adding another tagging line to each source file, specifying what symbols should be documented - like we already do for components and prefabs: __kamaelia_components__ = [ a, b, c ] __kamaelia_prefabs__ = [ p, q, r ] perhaps simply calling this extra one 'other': __kamaelia_other__ = [ x, y, z ] Any ideas? Matt -- | Matt Hammond | Research Engineer, FM&T, BBC, Kingswood Warren, Tadworth, Surrey, UK | http://www.bbc.co.uk/rd/ --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "kamaelia" group. To post to this group, send email to kamaelia@googlegroups.com To unsubscribe from this group, send email to kamaelia+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/kamaelia?hl=en -~----------~----~----~----~------~----~------~--~---