Create reference docs

[Synchro]

For many of the functions, there isn't any complete documentation - the main docs are more of a language overview that happens to mention most of them. Some of the colour functions have quite complex meanings and it would make the overview too long to incorporate them in there, so I suggest we create a separate reference documentation page that contains complete docs on every function. That way the main page can be slimmed down to provide a simpler overview without cluttering it with detail. Good idea?

[rmariuzzo]

@Synchro I think it is a great idea. You can count on me for adding the documentation for the 9 blending mode a pushed weeks ago. Where can I start from?

[Synchro]

I've done a rough draft of a reference page in my fork in templates/pages/reference.md. You'll find placeholders for the colour blending modes there. I moved the old file called 'reference.md' because it didn't contain any reference info, just testing config.

All function docs follow the same basic pattern:

• name
• description
• params
• result type
• example call and output

I don't know what you think of that layout, or whether (for example) we should describe the params inline with the function name. It struck me that for the color functions it would be very nice to have color chips next to each example so that it's not quite so abstract!

At the moment they're mostly in source-code order: they should probably be alphabetical within each section. It would also be useful to have a table of contents, but I've no idea how to build one in markdown!

Going through these functions made me realise that there may be some inconsistencies in accepted parameter formats - something that cropped up in this issue - and I want to be sure any of these are cleared up. For example, the threshold parameter in the contrast function I wrote could be a percentage or a float, but I don't know that both have been tested.

[lukeapage]

will look later.. but the test pages look wrong - I'm not aware that less.js uses vows.. maybe it should be deleted rather than moved

basically any function that accepts a percentage calls a number() function that converts 100% => 1 so it therefore accepts a percentage or a float. Whether the float is intended or not, I don't know.

[Synchro]

I'm looking at this in mix:

var p = weight.value / 100.0;

and this in contrast:

if (typeof threshold === 'undefined') {
    threshold = 0.43;
} else {
    threshold = threshold.value;
}

mix is expecting a percentage, and is doing the /100 itself. contrast is expecting a float, but will it work if given a percentage because it uses .value? Neither are calling a number() function. Are either/both wrong?

[rmariuzzo]

@Synchro, concerning the reference page, I took a look a it, and it looks great for me. I agree with you what would be nice to put some color chips side by each blending mode. I will start next week adding the proper reference for each blending mode.

I have a question, can I pull your fork to my fork then push my future changes (blending mode reference)?

[Synchro]

Yes, that's what I intended, that way we (and anyone else who cares to help!) can collaborate on getting the docs in good shape before we issue a pull request.

[Synchro]

Just wondering - should this flavour of the docs be done in the wiki, rather than as I've done them here?

[Synchro]

Any chance of an answer on this? I don't want to go any further on the docs if it's heading in the wrong direction, and docs updates are definitely needed for 1.3.x.

[rmariuzzo]

Im ready to write up the docs but Im clueless about where to put it.
Please, I need to know where to add it.

Rubens Mariuzzo
On Oct 4, 2012 2:37 AM, "Marcus Bointon" notifications@github.com wrote:

Any chance of an answer on this? I don't want to go any further on the
docs if it's heading in the wrong direction, and docs updates are
definitely needed for 1.3.x.

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/26#issuecomment-9131997.

[Synchro]

Well you can fork my repo and submit changes to that, but I'd like to be sure whether we should be doing it this way or putting stuff in the wiki. For the writing itself it probably doesn't matter much either way since they both use markdown, so just go ahead and write stuff wherever is convenient! I've been using a command-line markdown parser for testing.

[rmariuzzo]

Ok, I will start right away!

Rubens Mariuzzo
On Oct 4, 2012 11:01 AM, "Marcus Bointon" notifications@github.com wrote:

Well you can fork my repo and submit changes to that, but I'd like to be
sure whether we should be doing it this way or putting stuff in the wiki.
For the writing itself it probably doesn't matter much either way since
they both use markdown, so just go ahead and write stuff wherever is
convenient! I've been using a command-line markdown parser for testing.

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/26#issuecomment-9144361.

[lukeapage]

I don't think it matters too much where the documentation is.. Personally I would prefer an extra page on the website - I think its more visible than on the wiki.

I was hoping @cloudhead would give us rights to the website and npm for releases and this would allow us to update the documentation at the same time.

Documentation is probably the least fun aspect of open source so personally I applaud you for what you have done so far - thanks.

[rmariuzzo]

Just to let everybody know, maybe I'll finish the docs by the end of
October, because Im getting married in October 13th. ;-)

Rubens Mariuzzo
On Oct 7, 2012 6:35 AM, "Luke Page" notifications@github.com wrote:

I don't think it matters too much where the documentation is.. Personally
I would prefer an extra page on the website - I think its more visible than
on the wiki.

I was hoping @cloudhead https://github.com/cloudhead would give us
rights to the website and npm for releases and this would allow us to
update the documentation at the same time.

Documentation is probably the least fun aspect of open source so
personally I applaud you for what you have done so far - thanks.

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/26#issuecomment-9206846.

[Synchro]

Hope you had a great wedding! Recovered yet?
I just discovered that markdown doesn't allow setting colors 💩 which rather scuppers our plans for CSS color world domination.
In other news I was led to this Quicklook plugin (just grab the binary) which makes markdown previewing very easy, if you're on OS X.