Add documentation to port API #1313
Conversation
LaszloLango
added
development
docs/05.PORT-API.md
Outdated
|
|
||
| ## I/O | ||
|
|
||
| These should be the only I/O functions jerry calls. All calls to `printf`, `vfprintf`, and `putchar` should be rewritten to one of these, depending on what jerry wants to print. |
There was a problem hiding this comment.
These are the only functions jerry calls.
The rest can be deleted.
|
LGTM |
LaszloLango
force-pushed
the
jerry-port-how-to
branch
from
5a03e2e to
8bc8df3
Compare
docs/05.PORT-API.md
Outdated
|
|
||
| ## Termination | ||
|
|
||
| It is questionable whether a library should be able to terminate an application. However, as of now, we only have the concept of completion code around `jerry_parse` and `jerry_run`. Most of the other API functions have no way of signaling an error. So, we keep the termination approach with this port function. |
There was a problem hiding this comment.
Do we still have the concept of completion code around jerry_parse and jerry_run?
There was a problem hiding this comment.
Good question. AFAIK, "out of memory" errors can happen in jerry_create_... calls. @zherczeg ?
There was a problem hiding this comment.
Yes, anything that allocates memory (property setting, etc.).
There was a problem hiding this comment.
I mean, completion code is an old concept, which has been removed, AFAIK. Those functions return jerry_value_t nowadays. So that seems definitely like an outdated sentence.
docs/05.PORT-API.md
Outdated
|
|
||
| This header containt the decleration of port specific helper functions for termination and I/O. | ||
|
|
||
| ```C |
There was a problem hiding this comment.
Use consistent annotation of example language throughout the document. Either capital-C or small-c.
docs/05.PORT-API.md
Outdated
|
|
||
| # How to port JerryScript | ||
|
|
||
| This section describes the default port implementation which was created for Unix based systems. |
There was a problem hiding this comment.
I'm not sure that we should copy the default implementation verbatim here. From previous experiences, it seems that port creators often get confused by the default port-specific public helper methods (e.g., whether to abort or exit on failure). So, I think we should provide a simplified version here.
There was a problem hiding this comment.
I don't mind to simplify the documentation.
There was a problem hiding this comment.
I'd vote for providing a simpler example then. We just have to make sure that the example code works, of course...
LaszloLango
force-pushed
the
jerry-port-how-to
branch
from
8bc8df3 to
ffd79e4
Compare
|
@akosthekiss, @zherczeg: I've updated the PR. Please check. |
docs/05.PORT-API.md
Outdated
|
|
||
| ## Termination | ||
|
|
||
| It is questionable whether a library should be able to terminate an application. Some of the API functions may signal an error (ex.: cannot allocate memory). So, we keep the termination approach with this port function. |
There was a problem hiding this comment.
Only some of the API functions can signal an error ... for the others, we keep ...
|
If my last comment gets fixed, LGTM |
JerryScript-DCO-1.0-Signed-off-by: László Langó llango.u-szeged@partner.samsung.com
LaszloLango
force-pushed
the
jerry-port-how-to
branch
from
ffd79e4 to
2a354b2
Compare
|
|
||
| ## Termination | ||
|
|
||
| It is questionable whether a library should be able to terminate an application. Any API function can signal an error (ex.: cannot allocate memory), so the engine use the termination approach with this port function. |
There was a problem hiding this comment.
I would remove the "It is questionable whether a library should be able to terminate an application. " because the next sentence has no logical relation to it.
3 participants
JerryScript-DCO-1.0-Signed-off-by: László Langó llango.u-szeged@partner.samsung.com