Concise comments (for methods) in jQuery source code?
Sam Collett
jQuery to see how it works, it can be harder to understand since all
the ScriptDoc comments have been removed. Rather than go back to how
it used to be (with them in, which would mean a lot more work to keep
them in sync with the wiki), how about just a brief description of the
method and a link to the appropriate help page?
e.g.
// Removes elements matching the specified expression from the set of
matched elements.
// http://docs.jquery.com/Traversing/not
not: function( selector ) {
It would be a one-off change to the source (unless the docs url is
changed) as the behaviour of the method being described will not
change (just the parameters passed to it and how it is implemented).
Karl Swedberg
Sam Collett
(and maybe back again, if Trac turns hyperlinks in code to clickable
links). e.g. On 'not' wikipage, link to http://dev.jquery.com/browser/tags/1.2.1/src/core.js#L267
On Oct 5, 5:01 pm, Karl Swedberg <k...@englishrules.com> wrote:
> Hey Sam,
>
> For what it's worth, I agree with those on the dev list who thought
> this was a brilliant idea.
>
> --Karl
> _________________
> Karl Swedbergwww.englishrules.comwww.learningjquery.com
>
> On Oct 5, 2007, at 11:05 AM, Sam Collett wrote:
>
>
>
> > Since there are a few users who browse the uncompressed source code of
> > jQuery to see how it works, it can be harder to understand since all
> > the ScriptDoc comments have been removed. Rather than go back to how
> > it used to be (with them in, which would mean a lot more work to keep
> > them in sync with the wiki), how about just a brief description of the
> > method and a link to the appropriate help page?
>
> > e.g.
>
> > // Removes elements matching the specified expression from the set of
> > matched elements.
> > //http://docs.jquery.com/Traversing/not
Pyrolupus
As long as there is no pushback on this change, does it matter who
does the updates in the codebase?
Pyro
On Oct 5, 12:35 pm, Sam Collett <sam.coll...@gmail.com> wrote:
> You could have a link from the methods page straight to the source
> (and maybe back again, if Trac turns hyperlinks in code to clickable
> links). e.g. On 'not' wikipage, link tohttp://dev.jquery.com/browser/tags/1.2.1/src/core.js#L267
John Resig
--John
Daemach
group/jquery-dev/browse_thread/thread/1798f1876e325c60) regarding
Aptana's new integrated support for scriptDoc-style documentation.
More info here: http://aptana.com/docs/index.php/Documenting_your_code_using_ScriptDoc
On Oct 5, 5:02 pm, "John Resig" <jere...@gmail.com> wrote:
> Patches welcome! If someone pulled this together, I'd definitely apply it.
>
> --John
>
> On 10/5/07, Sam Collett <sam.coll...@gmail.com> wrote:
>
>
>
> > Since there are a few users who browse the uncompressed source code of
> > jQuery to see how it works, it can be harder to understand since all
> > the ScriptDoc comments have been removed. Rather than go back to how
> > it used to be (with them in, which would mean a lot more work to keep
> > them in sync with the wiki), how about just a brief description of the
> > method and a link to the appropriate help page?
>
> > e.g.
>
> > // Removes elements matching the specified expression from the set of
> > matched elements.
> > //http://docs.jquery.com/Traversing/not
Sam Collett
can convert the Wiki documentation into ScriptDoc somehow!
Sam Collett
Not done that much as I am not entirely sure what would be the best
way to document methods that are overloaded (attr is a good example of
this) - plus don't want to spend a lot of time doing something that
could be done better. I've also set the comments to be the same as the
Wiki (although in some cases (like with 'each'), maybe the Wiki should
be updated?).
On Oct 6, 1:02 am, "John Resig" <jere...@gmail.com> wrote:
> Patches welcome! If someone pulled this together, I'd definitely apply it.
>
> --John
>
> On 10/5/07, Sam Collett <sam.coll...@gmail.com> wrote:
>
>
>
> > Since there are a few users who browse the uncompressed source code of
> > jQuery to see how it works, it can be harder to understand since all
> > the ScriptDoc comments have been removed. Rather than go back to how
> > it used to be (with them in, which would mean a lot more work to keep
> > them in sync with the wiki), how about just a brief description of the
> > method and a link to the appropriate help page?
>
> > e.g.
>
> > // Removes elements matching the specified expression from the set of
> > matched elements.
> > //http://docs.jquery.com/Traversing/not
Daemach
way to do documentation - forward thinking. Aptana just took a while
in catching up. Now that they have, though, having those scriptDoc
documentation blocks within the code adds significant benefits.
Especially if plugin authors start taking advantage of this. I like
your idea as well, but it would be nice if you could work it into the
same sciptDoc style for compatibility's sake. I'm worried that now,
just as Aptana released this functionality, everyone is going to want
to switch how they do documentation and break that support.
I spoke with ingo at Aptana yesterday. the scriptDoc implementation
they are using is not currently extensible, but they are going to add
the @example param after I asked for it. I assume they would be
willing to add anything else that made sense as well.
FWIW