[Dev] Re: Using the description string to document attributes

[John Anderson]

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):
> http://chandler.osafoundation.org/docs/0.6/schema-types.html

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.
>
> Cheers,
> Katie
>
>
> 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.
>>
>> Reactions?
>>
>> - Donn
>
>
> _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
>
> Open Source Applications Foundation "Dev" mailing list
> http://lists.osafoundation.org/mailman/listinfo/dev