|
|
Re: documenting widgets was: release 0.4.1 bug triage: msg#00508
web.dojo.devel
|
Subject: |
Re: documenting widgets was: release 0.4.1 bug triage |
Thanks Tom.
I guess then I don't follow the discussion about documention for the
widgets in
the code. Will that info get picked up by the parser? Is it now?
Thanks,
Carla
Tom Trenka wrote:
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
<mailto: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
<mailto:dojo-contributors@xxxxxxxxxxxxxxx>
>> http://dojotoolkit.org/mailman/listinfo/dojo-contributors
>
> _______________________________________________
> dojo-contributors mailing list
> dojo-contributors@xxxxxxxxxxxxxxx
<mailto:dojo-contributors@xxxxxxxxxxxxxxx>
> http://dojotoolkit.org/mailman/listinfo/dojo-contributors
_______________________________________________
dojo-contributors mailing list
dojo-contributors@xxxxxxxxxxxxxxx
<mailto:dojo-contributors@xxxxxxxxxxxxxxx>
http://dojotoolkit.org/mailman/listinfo/dojo-contributors
<http://dojotoolkit.org/mailman/listinfo/dojo-contributors>
------------------------------------------------------------------------
_______________________________________________
dojo-contributors mailing list
dojo-contributors@xxxxxxxxxxxxxxx
http://dojotoolkit.org/mailman/listinfo/dojo-contributors
|
|
