[Sugar-devel] [Karma] pls review jsdocs for Karma

[Bryan Berry]

first, tks for the awesome feedback

2009/12/14 Felipe López Toledo <zer.subzero at gmail.com>

> hey man,
>
> I have read the online docs, here is my feedback:
>
> [ feature request ]
> add collision support for file names repeated
>

Can you be more specific? just to avoid loading the same file twice?

I think that collision support for the 'name' property would also be helpful


> [ question ]
> how does the actual localization algorithm work?
> I mean, is there a way to localize all the content with one line?
> maybe, we could explain it in the docs
>

It doesn't work ;) ! there is no localization at all. It will have to wait
until next release


> [ bug? ]
> maybe, I'm wrong, but I think here is an error:
> /docs/symbols/Karma.html
> - ninja1.sword === "sword"

+ ninja1.weapon === "sword"
>

that is a bug, thanks for catching it


> [ suggestion ]
> /docs/symbols/Karma.karma.html
> Karma.karma.locale
> what is the default value?, I suggest "en"
>

none, right now, let me think about this.



> [ request ]
> /docs/symbols/Karma.kCanvas.html
> please, delete "fps" property, atm it does not have any function.
>

done


> [ suggestion ]
> I have seen some examples with code an explanation, I suggest to addcomment characters(/* */)
>
> example:
>
> docs/symbols/Karma.karma.html
> Karma.karma.rand(lower, upper)
> var num = rand(0, 10);
> - num could be 0, 1, 2, 3 ... or 10
> + //num could be 0, 1, 2, 3 ... or 10 <-----
>

great idea


> [ ]
> btw, I see there is no kimage, ksound and so on documentation, I think it
> is  the problem with the JsDoc toolkit, right?
>
> regards


Yeah, it has to do with jsdoc toolkit but also the funny way I laid out
kMedia prototype object for them both. I now think it is probably better
that I get rid of kMedia and just split them into 3 wholly different objects
without a prototypal parent. It is odd to make a concession for the
documentation tool but I also think that it will make the code easier to
read.


>
> 2009/12/3 Bryan Berry <bryan at olenepal.org>
>
>> argh! sorry I forgot the link
>> http://karma.sugarlabs.org/docs/index.html
>>
>> 2009/12/3 Bryan Berry <bryan at olenepal.org>
>>
>> I have added examples but there is still work to be done. Please let me
>>> know if it is hard to follow or if significant chunks are missing
>>>
>>> I haven't exactly figured out how to document methods like play() since
>>> there isn't an object specific to it
>>>
>>> I also haven't documented the kCanvas with the makeChain function. I fear
>>> that the makeChain function -- while truly a feat of metaprogramming and
>>> closure manipulation -- may be too clever. It also may not save that much
>>> typing since I will have to document each function anyways. Felipe what do
>>> you think?
>>>
>>
>>
>
>
> --
> Felipe López Toledo
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.sugarlabs.org/archive/sugar-devel/attachments/20091215/ebfd623c/attachment-0001.htm