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
-~----------~----~----~----~------~----~------~--~---

Reply via email to