Re: documenting widgets was: release 0.4.1 bug triage

Carla,

I can't speak for anyone else but it was my impression that what is generated by the API docs is not the same as what needs to be in the book; the API docs are more of a reference, but in the end there still needs to be some sort of user-friendly User Guide--and my understanding was that was going to have to be manually written, regardless of what is in the code itself.

Anyone know any different, I'd be glad to hear it.

trt

On 10/30/06, Carla Mott <Carla.Mott@xxxxxxx > wrote:

Hi,

I'd like to get clarification on documenting widgets.  If the
documentation is
in the source file then is there a way to automatically generate
documentation
for users that will be appropriate for the book?

I'm looking for user documentation.  Putting the info in the source file
will
help to keep it up to date but if the user must read code then how is that
different than what we have now?

What I like about the JavaDocs (I know some of you hate it) on the last
project I worked on is I can get a release bundle and the corresponding
JavaDocs each week.  What is nice is that we automatically generate and
publish
both on a regular basis.  It is really helpful for developers.

What is the process for generating the API  docs?  Once things settle
down with
that task what is the process for generating and updating the docs?

If the widget info is in the source file will the above process collect
that info too?
I assumed the answer is no but now I'm not sure. If the parser does
collect that
data then how does it get in the book?  Is it part of the API doc or
something else?

Since the book is a wiki there is, I think, an expectation that we can
and will update
it any time during the development cycle.  If we can get the widget info
that is in the source file in a format that is useful for the book then
great.  If
not then I think we need to put that info in the book and work to keep
that up
to date.  Regardless, I think there is additional info that should be
added such as
examples.  I always thought that the API docs and the book complement each
other.  Now I need to know what the API docs have so I can figure out what
needs to be in the book.

Thanks,
Carla


Bill Keese wrote:

> I don't think the templateCssPath has anything to do with whether
> templateCssPath is declared in the initializer or the prototype.
> After all, we have lots of widgets that have string parameters and
> they work fine.  Obviously, loading two CSS files that define
> conflicting rules for .dojoToolbar is no good, but that's an unrelated
> issue.
>
> Like I said in my last mail, show me some examples of these subtle
> problems of which you speak.  I stress the word *example*.
>
>
> Tom Trenka wrote:
>
>> The templatePath/templateCssPath issue I'm referring to is the one
>> where you can "override" the default value set in a widget by adding
>> that attribute to a widget's markup:
>>
>> <div dojoType="someWidget"
>> templateCssPath="../../path/to/css.css"></div>
>>
>> ...we've known for a long time that doing this will cause *all*
>> widgets of type someWidget to use the new CSS template as opposed to
>> the one defined in the widget code (you, me and Dustin talked about
>> it briefly when we started talking about theming solutions).    The
>> reason for this is because it is a shared property--because it's been
>> defined on the prototype of the widget and not the widget itself.
>>
>> You can declare widget parameters within extend just fine--if you
>> understand the consequences of that definition.  A good example would
>> be the declaration of values that shouldn't be touched by a user of
>> the widget at all, such as isContainer or widgetType.  But full
>> understanding of *exactly* what is going on when doing that is really
>> needed.  I'm not convinced that's the case; as you've mentioned, it's
>> less full understanding and more "this is a convention that Alex
>> started".
>>
>>     Hmm, well if it doesn't work then we have to change it.  As usual, I
>>     don't care much either way but I want to have a standard that
>> everyone
>>     follows.  (Here an inconsistency is especially bad since things
>> declared
>>     in a base class's initializer will overwrite things declared in the
>>     subclass's prototype.)
>>
>>
>> It's not as much "overwrite" as much as it is "masks"; minor point
>> but we're about to get back into the whole language terminology
>> argument, so I'll leave that for a different thread.  Either way I
>> agree, we should have a standard.  I also think this change should be
>> a 0.5 one and not a 0.4.1 one, so...I suggest we at least hold off
>> until after any kind of sub-point release is made (or branch, for
>> that matter).
>>
>> trt
>>
>>
>> ------------------------------------------------------------------------
>>
>> _______________________________________________
>> dojo-contributors mailing list
>> dojo-contributors@xxxxxxxxxxxxxxx
>> http://dojotoolkit.org/mailman/listinfo/dojo-contributors
>
> _______________________________________________
> dojo-contributors mailing list
> dojo-contributors@xxxxxxxxxxxxxxx
> http://dojotoolkit.org/mailman/listinfo/dojo-contributors


_______________________________________________
dojo-contributors mailing list
dojo-contributors@xxxxxxxxxxxxxxx
http://dojotoolkit.org/mailman/listinfo/dojo-contributors

_______________________________________________
dojo-contributors mailing list
dojo-contributors@xxxxxxxxxxxxxxx
http://dojotoolkit.org/mailman/listinfo/dojo-contributors