Re: new API Ref up

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

How did Bill steal Neil's login? ;)

All kidding aside, I think it is a good question that we have long
ignored, and instead we've sort of gone with the approach of "what are
people asking for, and is it reasonable." and usually what has won is
what has been coded.

Neil Roberts wrote:
> Where do we stop growing the parser? The original plan was for the parser
> to be a tool, to do some simple things, and the front end can do the rest.
> This, like many areas of our codebase, is growing from a simple tool into
> a full-fledged framework. The feature set of the parser is already rich,
> and every day it's getting richer.
> 
> I need to know, is this what we really want? And if it is, is it worth the
> development cost of adding all these extra features? Is it really making
> our documentation better?
> 
> Can we at least develop a process to determine how we want to add new
> features? Because I feel like a jerk for continually saying the parser
> can't do X or Y. And if I were to implement every X or Y that was asked,
> would we all be happy with the result?
> 
> -Neil
> 
>> There should be no markup in comments. This is what the external storage
>> is for, for exactly this type of thing. I'll get this working as fast as I
>> can, but the parser does not handle code inside of comments inside of
>> code.
>>
>> -Neil
>>
>>> I assume you're referring to the "pre" formatting (indentation and
>>> newlines) of the dojo.event.connect examples in that function.
>>>
>>> The parser is outputting the "summary" in the "local/json" output
>>> without newlines or any new line markers, and smooshing all the white
>>> space, so there's nothing I can do in the front end at this point.
>>> What I suggest is this:
>>>
>>> 1) we come up with a convention to indicate "this is a code block" in
>>> comments
>>> 2) the parser encodes newlines as "\n" and leaves in spaces in
>>> summary/description blocks (like it does with src blocks)
>>> 3) the front end will strip out all newlines except those that sit
>>> inside a code block, and will <pre> (at least) the code blocks.
>>>
>>> Alternatively, we could define an "example" keyword, like the summary/
>>> description/etc keywords, which would be treated just like the "src"
>>> block.  It's not as flexible, but would be easy to do.  Separating
>>> out the examples from the summary would be nice from a visual
>>> standpoint when the API viewer is in "summary" mode.
>>>
>>> Also, Alex, I recommend that extended text like that go in a
>>> "description" block rather than "summary."
>>>
>>> Thoughts?  Neil?
>>>
>>> thanks
>>> O
>>>
>>> -------------------------
>>> Whenever I despair, I remember that the way of truth and love has
>>> always won. There may be tyrants and murderers, and for a time, they
>>> may seem invincible, but in the end, they always fail. Think of it:
>>> always.  -- Mohandas K. Ghandi
>>>
>>>
>>> On Oct 29, 2006, at 11:10 PM, Alex Russell wrote:
>>>
>>>> Is there some way to get some block of formatting preserved from the
>>>> source comments. In particular, the docs for dojo.event.connect are
>>>> pretty badly mangled and I'd like to know how to "pass through" some
>>>> amount of formatting.
>>>>
>>>> Regards
>>>>
>>>> On Sunday 29 October 2006 9:17 pm, Owen Williams wrote:
>>>>> http://dojotoolkit.org/api
>>>>>
>>>>> No functional changes, just updated to use new parser output.
>>>>>
>>>>> Checked in as revision 6368.
>>>>>
>>>>> Enjoy
>>>>> O
>>>>> -------------------------
>>>>> Whenever I despair, I remember that the way of truth and love has
>>>>> always won. There may be tyrants and murderers, and for a time, they
>>>>> may seem invincible, but in the end, they always fail. Think of it:
>>>>> always.  -- Mohandas K. Ghandi
>>>> --
>>>> Alex Russell
>>>> alex@xxxxxxxxxxx     A99F 8785 F491 D5FD 04D7 ACD9 4158 FFDF 2894 6876
>>>> alex@xxxxxxxxxxxxxxx BE03 E88D EABB 2116 CC49 8259 CF78 E242 59C3 9723
>>>> _______________________________________________
>>>> 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
> 
> 
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.1 (Darwin)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFFRlCX8nLgh/JJsxERAn2zAKCCkk93Z4poinLrhLFOwD/9z5yzigCghLVq
Vobkh00E9P75U3ko7ufNy2A=
=cZJR
-----END PGP SIGNATURE-----