[Dev] Re: Using the description string to document attributes
john at osafoundation.org
Sat Dec 3 16:34:40 PST 2005
Katie Capps Parlante wrote:
> (Replying to dev because I think it is of general interest)
> Hi Donn,
> An idea emerged at the PyCon sprint that it would be really useful to
> have a brief "cheat sheet" of both repository types and blocks/events.
> Ted has done a pass at the schema types (after our 0.6 schema api work
> it makes more sense to document types to be used with the schema api):
It would be handy to add to this list of types, limitations on what kind
of types can go in compound types that you wouldn't expect if you were a
python programmer, e.g. ref collections can only have references. Lists
that contain literals can't contain bidirectional refs. How
bidirectional refs differ from single refs, etc.
> I think we were imagining something similar for a list of
> blocks/events that might be of interest to someone experimenting with
> writing parcels.
> So perhaps there are two questions here:
> * Is it a good idea to update description strings on blocks and events
> that might appear in a parcel, with a convention of using
> "Required"/"Recommended"/"Optional" at the beginning of the string?
> +1 sounds reasonable to me
I think it was Bryan who proposed that we come up with a epydoc syntax
to document attributes. This would be really handy for Blocks/Events
since so much of how you use them is by setting their attributes.
> * Can we use the repository viewer instead of a separate cheat sheet
> doc that will be out of sync if we don't update it?
> I'm interested in other opinions about this one.
> Donn Denman wrote:
>> Katie and Morgen,
>> I'm tasked with documenting Blocks and Events for parcel writers,
>> and it seems to me that leveraging off of your
>> web-repository-viewer would be a huge help. It's got all the
>> information, just no guidance! One of the things missing is
>> description strings on almost all the CPIA attributes saying what
>> they do! The other piece, which I find to be critical, is a
>> "required from user" bit, that basically says "you, the parcel
>> writer, should supply a setting for this attribute". I don't want
>> to add a bit to any schema for this (especially now), but I was
>> thinking we could just have a convention in the documentation
>> attribute, to start it with "Required" or "Optional", but I'm not
>> 100% happy with this. There's no way to quickly and easily tell
>> which attributes are used internally by the system, and are rarely
>> user-supplied, and which ones are critical user-supplied settings.
>> I can write a guide that answers these questions, but it will get
>> out of date over time -- the information really belongs on the
>> attributes, in my opinion.
>> So I propose that I update the description strings an most things
>> that might appear in a parcel, and use the convention that the
>> string will start with:
>> "Required" for things you always need to supply
>> "Recommended" for things you usually need to supply
>> "Optional" for things you sometimes supply
>> Anything else means it's either an internal thing or an inverse or
>> something you don't really need to understand.
>> Then I'll leverage off of this in my write-up.
>> - Donn
> _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
> Open Source Applications Foundation "Dev" mailing list
More information about the Dev