search

Automattic / node-canvas

Node canvas is a Cairo backed Canvas implementation for NodeJS.
10.17k stars 1.17k forks source link

Can't find docs on this library's objects #1031

Open pinuke opened 7 years ago

pinuke commented 7 years ago

The Canvas API itself from HTML5 can be found on MDN, and the non-standard Canvas API is documented here. My question doesn't regard those docs (I think).

My question is, is there an API documentation for how to use the new objects provided by this library?

I found this question on SO: https://stackoverflow.com/questions/9548074/nodejs-how-to-add-image-data-from-file-into-canvas

This particular snippet within it is concerning:

var canvas = new Canvas( img.width, img.height )

Where Canvas is defined here:

Canvas = require('canvas');

However, I didn't find any resource documenting this API. All I found was documentation on Canvas.createCanvas, and even then there is no description of what createCanvas does, what arguments it takes, and what kind of properties the function has as a javascript object.

Another API that seems to be mysterious is the new Image() API. I am assuming it is identical to Image() defined by the HTML Living Standard (MDN), but again there is no doc, not even a sentence saying that "node-canvas Image() = HTML living standard Image()"

How am I supposed to know how your implementation of Image() differs from say Mozilla Firefox's implementation of Image()?

pinuke commented 7 years ago

Note to Self

I am not a C developer (of any kind), so I will leave digging through the source code alone for now.

I will go throw the massive ton of issues to see if I can find anything

pinuke commented 7 years ago

Note to Self

found this issue: https://github.com/Automattic/node-canvas/issues/997

pinuke commented 7 years ago

Note to Self

Using the search queries "is:issue image NOT install" and "is:issue canvas NOT install" gives many issues with example usages of Image and Canvas

However, I still have found nothing documenting the overall architecture of the constructors/objects:

Image() Canvas() (and from issue #997) createCanvas()

I may have to dig through the source code to get these details.

LinusU commented 7 years ago

Would love to accept PRs for better documentation!

pinuke commented 7 years ago

@LinusU I would be happy to help, but I will have to do some extensive research into the source, especially since I am not a C developer. Just something for thought...

zbjornson commented 7 years ago

@smartguy1196 Everything in this repo should mirror the native HTML objects (Image, ImageData, <canvas>, DOMMatrix, DOMPoint, CanvasRenderingContext2D, TextMetrics), with the exception of anything listed in the readme as non-standard. If there's anything that doesn't match between this module and HTML and that's not listed in the readme, it is most likely a bug.

There are some examples in the examples folder also, btw.

pinuke commented 6 years ago

@zbjornson appreciated.

I am guessing the reason that this isn't explicitly documented is that there are still some features to implement?

Note:

I do plan to help with documentation, and would be happy to do so. It is something I pride myself in, but right now I am consumed by my own repositories.

As soon as I get some good free time, I will gladly dive right into your code and translate what it does into a readable format.

zbjornson commented 6 years ago

I am guessing the reason that this isn't explicitly documented is that there are still some features to implement?

For myself at least, I've prioritized fixing bugs in the time I have for open-source work, but I agree docs would be nice. As far as features to implement, node-canvas is pretty complete (see https://github.com/Automattic/node-canvas/wiki/Compatibility-Status). The spec keeps evolving of course; there's no support for ImageBitmap & friends, for example.

I do plan to help with documentation

Awesome :).