[Moo] [request] mootools documentation to link to relevant sources

[Dimitar Christoff]

just an idea...

I think this would be beneficial - can we have it so that when in docs,
say...

http://mootools.net/docs/more/Interface/Tips

it has a direct link to tips.js where you can look at the code and
figure out all possible ways to use it.

cheers
--
Dimitar Christoff <[hidden email]> - http://fragged.org/

[fakedarren]

Hi Dimitar,

We would not wish to link directly to the source for any MooTools
component from the documentation - simply because we do not list all
methods in the documentation, as some are internal / private. If we
did what you suggest, no doubt we would then constantly be asked 'why
isn't method foo() listed on the docs page?'. Using these methods is
done at the user's own risk as we will not offer any compatibility
with future versions for internal methods.....

We do however intend to add links to documentation pages - but rather
to blog posts, demos and tutorials about that particular item.

Although, reading the source code is an excellent way to learn more
about the various parts of MooTools!

Cheers
Darren

On Oct 29, 11:03 am, Dimitar Christoff <[hidden email]> wrote:

> just an idea...
>
> I think this would be beneficial - can we have it so that when in docs,
> say...
>
> http://mootools.net/docs/more/Interface/Tips
>
> it has a direct link to tips.js where you can look at the code and
> figure out all possible ways to use it.
>
> cheers
> --
> Dimitar Christoff <[hidden email]> -http://fragged.org/

[Dimitar Christoff]

Hey FakeDaz :D

> We would not wish to link directly to the source for any MooTools
> component from the documentation - simply because we do not list all
> methods in the documentation, as some are internal / private.

you got it in one - and this is exactly WHY i want to have easy access
to the the source--in view of extending a class or whatever, or doing
something outside of its intended scope when in a hurry...

how is a link to the relevant trunk going to be an issue, i don't know.
it's available anyway, this is just making it easier.

and as you say, showing native/core code will do nothing but improve
people's coding practices as a whole.
--
Dimitar Christoff <[hidden email]> - http://fragged.org/

[anutron]

My argument against it isn't so much that we want to protect the source from being perused but rather that we should keep the docs as clean and unconfusing for people as possible. Anyone who wants to view the source just has to pull it down from git and open it in TextMate (or browse it on github). The docs are an API reference. If you want to use the MooTools API, in theory they should be all you need and, as Darren points out, it protects both us and you by plainly illustrating our contract with you, the user, as to what we support.

But anyone who is going to go deeper than that is just going to download the library itself. Indeed, I almost always have the entire MooTools collection of files (-core, -more, clientcide, art, etc) in a Textmate project that's open, and I'm probably more likely to just switch to it, hit command-T and open the file I'm curious about and read the source than I am to go online and look at the docs.

On Thu, Oct 29, 2009 at 7:19 AM, Dimitar Christoff <[hidden email]> wrote:

Hey FakeDaz :D

> We would not wish to link directly to the source for any MooTools
> component from the documentation - simply because we do not list all
> methods in the documentation, as some are internal / private.

you got it in one - and this is exactly WHY i want to have easy access
to the the source--in view of extending a class or whatever, or doing
something outside of its intended scope when in a hurry...

how is a link to the relevant trunk going to be an issue, i don't know.
it's available anyway, this is just making it easier.

and as you say, showing native/core code will do nothing but improve
people's coding practices as a whole.
--
Dimitar Christoff <[hidden email]> - http://fragged.org/

[Jan Kassens]

Some javascript/style in this post has been disabled (why?)

I think its a nice idea! Not per method links (not possible because of generated functions etc), but just a quick link to the source for the currently viewed file.

I don’t think it’s a bad idea to encourage people to take a look at the source. Some of them might see, that the source isn’t that complex (besides some core files) and might get engaged in improving it!

Jan

On 29.10.2009, at 16:39, Aaron Newton wrote:

My argument against it isn't so much that we want to protect the source from being perused but rather that we should keep the docs as clean and unconfusing for people as possible. Anyone who wants to view the source just has to pull it down from git and open it in TextMate (or browse it on github). The docs are an API reference. If you want to use the MooTools API, in theory they should be all you need and, as Darren points out, it protects both us and you by plainly illustrating our contract with you, the user, as to what we support.

But anyone who is going to go deeper than that is just going to download the library itself. Indeed, I almost always have the entire MooTools collection of files (-core, -more, clientcide, art, etc) in a Textmate project that's open, and I'm probably more likely to just switch to it, hit command-T and open the file I'm curious about and read the source than I am to go online and look at the docs.

On Thu, Oct 29, 2009 at 7:19 AM, Dimitar Christoff <[hidden email]> wrote:

Hey FakeDaz :D

> We would not wish to link directly to the source for any MooTools
> component from the documentation - simply because we do not list all
> methods in the documentation, as some are internal / private.

you got it in one - and this is exactly WHY i want to have easy access
to the the source--in view of extending a class or whatever, or doing
something outside of its intended scope when in a hurry...

how is a link to the relevant trunk going to be an issue, i don't know.
it's available anyway, this is just making it easier.

and as you say, showing native/core code will do nothing but improve
people's coding practices as a whole.
--
Dimitar Christoff <[hidden email]> - http://fragged.org/