jyapayne/Nim
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

clean up the docs of some modules under lib/js (#16579)

Browse source
This commit is contained in:
flywind 2021-01-04 12:54:33 -06:00 • committed by GitHub
commit fe20492f05
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
8 changed files with 55 additions and 56 deletions
Download patch file Download diff file Expand all files Collapse all files

30
lib/js/asyncjs.nim
View file

@ -11,11 +11,11 @@
## and libraries, writing async procedures in Nim and converting callback-based code ## and libraries, writing async procedures in Nim and converting callback-based code
## to promises. ## to promises.
## ##
## A Nim procedure is asynchronous when it includes the ``{.async.}`` pragma. It ## A Nim procedure is asynchronous when it includes the `{.async.}` pragma. It
## should always have a ``Future[T]`` return type or not have a return type at all. ## should always have a `Future[T]` return type or not have a return type at all.
## A ``Future[void]`` return type is assumed by default. ## A `Future[void]` return type is assumed by default.
## ##
## This is roughly equivalent to the ``async`` keyword in JavaScript code. ## This is roughly equivalent to the `async` keyword in JavaScript code.
## ##
## .. code-block:: nim ## .. code-block:: nim
## proc loadGame(name: string): Future[Game] {.async.} = ## proc loadGame(name: string): Future[Game] {.async.} =
@ -28,14 +28,14 @@
## // code ## // code
## } ## }
## ##
## A call to an asynchronous procedure usually needs ``await`` to wait for ## A call to an asynchronous procedure usually needs `await` to wait for
## the completion of the ``Future``. ## the completion of the `Future`.
## ##
## .. code-block:: nim ## .. code-block:: nim
## var game = await loadGame(name) ## var game = await loadGame(name)
## ##
## Often, you might work with callback-based API-s. You can wrap them with ## Often, you might work with callback-based API-s. You can wrap them with
## asynchronous procedures using promises and ``newPromise``: ## asynchronous procedures using promises and `newPromise`:
## ##
## .. code-block:: nim ## .. code-block:: nim
## proc loadGame(name: string): Future[Game] = ## proc loadGame(name: string): Future[Game] =
@ -44,7 +44,7 @@
## resolve(game) ## resolve(game)
## return promise ## return promise
## ##
## Forward definitions work properly, you just need to always add the ``{.async.}`` pragma: ## Forward definitions work properly, you just need to always add the `{.async.}` pragma:
## ##
## .. code-block:: nim ## .. code-block:: nim
## proc loadGame(name: string): Future[Game] {.async.} ## proc loadGame(name: string): Future[Game] {.async.}
@ -57,10 +57,10 @@
## If you need to use this module with older versions of JavaScript, you can ## If you need to use this module with older versions of JavaScript, you can
## use a tool that backports the resulting JavaScript code, as babel. ## use a tool that backports the resulting JavaScript code, as babel.
import jsffi import std/jsffi
import macros import std/macros
when not defined(js) and not defined(nimdoc) and not defined(nimsuggest): when not defined(js) and not defined(nimsuggest):
{.fatal: "Module asyncjs is designed to be used with the JavaScript backend.".} {.fatal: "Module asyncjs is designed to be used with the JavaScript backend.".}
type type
@ -69,7 +69,7 @@ type
## Wraps the return type of an asynchronous procedure. ## Wraps the return type of an asynchronous procedure.
PromiseJs* {.importcpp: "Promise".} = ref object PromiseJs* {.importcpp: "Promise".} = ref object
## A JavaScript Promise ## A JavaScript Promise.
proc replaceReturn(node: var NimNode) = proc replaceReturn(node: var NimNode) =
@ -139,7 +139,7 @@ proc generateJsasync(arg: NimNode): NimNode =
macro async*(arg: untyped): untyped = macro async*(arg: untyped): untyped =
## Macro which converts normal procedures into ## Macro which converts normal procedures into
## javascript-compatible async procedures ## javascript-compatible async procedures.
if arg.kind == nnkStmtList: if arg.kind == nnkStmtList:
result = newStmtList() result = newStmtList()
for oneProc in arg: for oneProc in arg:
@ -149,8 +149,8 @@ macro async*(arg: untyped): untyped =
proc newPromise*[T](handler: proc(resolve: proc(response: T))): Future[T] {.importcpp: "(new Promise(#))".} proc newPromise*[T](handler: proc(resolve: proc(response: T))): Future[T] {.importcpp: "(new Promise(#))".}
## A helper for wrapping callback-based functions ## A helper for wrapping callback-based functions
## into promises and async procedures ## into promises and async procedures.
proc newPromise*(handler: proc(resolve: proc())): Future[void] {.importcpp: "(new Promise(#))".} proc newPromise*(handler: proc(resolve: proc())): Future[void] {.importcpp: "(new Promise(#))".}
## A helper for wrapping callback-based functions ## A helper for wrapping callback-based functions
## into promises and async procedures ## into promises and async procedures.

2
lib/js/dom.nim
View file

@ -10,7 +10,7 @@
## Declaration of the Document Object Model for the `JavaScript backend ## Declaration of the Document Object Model for the `JavaScript backend
## <backends.html#backends-the-javascript-target>`_. ## <backends.html#backends-the-javascript-target>`_.
import std/private/since import std/private/since
when not defined(js) and not defined(Nimdoc): when not defined(js):
{.error: "This module only works on the JavaScript platform".} {.error: "This module only works on the JavaScript platform".}
const const

2
lib/js/dom_extensions.nim
View file

@ -1,4 +1,4 @@
import dom import std/dom
{.push importcpp.} {.push importcpp.}
proc elementsFromPoint*(n: DocumentOrShadowRoot; x, y: float): seq[Element] proc elementsFromPoint*(n: DocumentOrShadowRoot; x, y: float): seq[Element]

2
lib/js/jsconsole.nim
View file

@ -12,7 +12,7 @@
import std/private/since, std/private/miscdollars # toLocation import std/private/since, std/private/miscdollars # toLocation
when not defined(js) and not defined(Nimdoc): when not defined(js):
{.error: "This module only works on the JavaScript platform".} {.error: "This module only works on the JavaScript platform".}
type Console* = ref object of JsRoot type Console* = ref object of JsRoot

4
lib/js/jscore.nim
View file

@ -11,10 +11,10 @@
## ##
## Unless your application has very ## Unless your application has very
## specific requirements and solely targets JavaScript, you should be using ## specific requirements and solely targets JavaScript, you should be using
## the relevant functions in the ``math``, ``json``, and ``times`` stdlib ## the relevant functions in the `math`, `json`, and `times` stdlib
## modules instead. ## modules instead.
when not defined(js) and not defined(Nimdoc): when not defined(js):
{.error: "This module only works on the JavaScript platform".} {.error: "This module only works on the JavaScript platform".}
type type

68
lib/js/jsffi.nim
View file

@ -8,8 +8,8 @@
# #
## This Module implements types and macros to facilitate the wrapping of, and ## This Module implements types and macros to facilitate the wrapping of, and
## interaction with JavaScript libraries. Using the provided types ``JsObject`` ## interaction with JavaScript libraries. Using the provided types `JsObject`
## and ``JsAssoc`` together with the provided macros allows for smoother ## and `JsAssoc` together with the provided macros allows for smoother
## interfacing with JavaScript, allowing for example quick and easy imports of ## interfacing with JavaScript, allowing for example quick and easy imports of
## JavaScript variables: ## JavaScript variables:
@ -24,18 +24,18 @@ runnableExamples:
proc jq(selector: JsObject): JsObject {.importcpp: "$$(#)".} proc jq(selector: JsObject): JsObject {.importcpp: "$$(#)".}
# Use jQuery to make the following code run, after the document is ready. # Use jQuery to make the following code run, after the document is ready.
# This uses an experimental ``.()`` operator for ``JsObject``, to emit # This uses an experimental `.()` operator for `JsObject`, to emit
# JavaScript calls, when no corresponding proc exists for ``JsObject``. # JavaScript calls, when no corresponding proc exists for `JsObject`.
proc main = proc main =
jq(document).ready(proc() = jq(document).ready(proc() =
console.log("Hello JavaScript!") console.log("Hello JavaScript!")
) )
when not defined(js) and not defined(nimdoc) and not defined(nimsuggest): when not defined(js) and not defined(nimsuggest):
{.fatal: "Module jsFFI is designed to be used with the JavaScript backend.".} {.fatal: "Module jsFFI is designed to be used with the JavaScript backend.".}
import macros, tables import std/[macros, tables]
const const
setImpl = "#[#] = #" setImpl = "#[#] = #"
@ -93,21 +93,21 @@ type
var var
jsArguments* {.importc: "arguments", nodecl}: JsObject jsArguments* {.importc: "arguments", nodecl}: JsObject
## JavaScript's arguments pseudo-variable ## JavaScript's arguments pseudo-variable.
jsNull* {.importc: "null", nodecl.}: JsObject jsNull* {.importc: "null", nodecl.}: JsObject
## JavaScript's null literal ## JavaScript's null literal.
jsUndefined* {.importc: "undefined", nodecl.}: JsObject jsUndefined* {.importc: "undefined", nodecl.}: JsObject
## JavaScript's undefined literal ## JavaScript's undefined literal.
jsDirname* {.importc: "__dirname", nodecl.}: cstring jsDirname* {.importc: "__dirname", nodecl.}: cstring
## JavaScript's __dirname pseudo-variable ## JavaScript's __dirname pseudo-variable.
jsFilename* {.importc: "__filename", nodecl.}: cstring jsFilename* {.importc: "__filename", nodecl.}: cstring
## JavaScript's __filename pseudo-variable ## JavaScript's __filename pseudo-variable.
proc isNull*[T](x: T): bool {.noSideEffect, importcpp: "(# === null)".} proc isNull*[T](x: T): bool {.noSideEffect, importcpp: "(# === null)".}
## check if a value is exactly null ## Checks if a value is exactly null.
proc isUndefined*[T](x: T): bool {.noSideEffect, importcpp: "(# === undefined)".} proc isUndefined*[T](x: T): bool {.noSideEffect, importcpp: "(# === undefined)".}
## check if a value is exactly undefined ## Checks if a value is exactly undefined.
# Exceptions # Exceptions
type type
@ -122,7 +122,7 @@ type
# New # New
proc newJsObject*: JsObject {.importcpp: "{@}".} proc newJsObject*: JsObject {.importcpp: "{@}".}
## Creates a new empty JsObject ## Creates a new empty JsObject.
proc newJsAssoc*[K: JsKey, V]: JsAssoc[K, V] {.importcpp: "{@}".} proc newJsAssoc*[K: JsKey, V]: JsAssoc[K, V] {.importcpp: "{@}".}
## Creates a new empty JsAssoc with key type `K` and value type `V`. ## Creates a new empty JsAssoc with key type `K` and value type `V`.
@ -137,20 +137,20 @@ proc jsTypeOf*(x: JsObject): cstring {.importcpp: "typeof(#)".}
proc jsNew*(x: auto): JsObject {.importcpp: "(new #)".} proc jsNew*(x: auto): JsObject {.importcpp: "(new #)".}
## Turns a regular function call into an invocation of the ## Turns a regular function call into an invocation of the
## JavaScript's `new` operator ## JavaScript's `new` operator.
proc jsDelete*(x: auto): JsObject {.importcpp: "(delete #)".} proc jsDelete*(x: auto): JsObject {.importcpp: "(delete #)".}
## JavaScript's `delete` operator ## JavaScript's `delete` operator.
proc require*(module: cstring): JsObject {.importc.} proc require*(module: cstring): JsObject {.importc.}
## JavaScript's `require` function ## JavaScript's `require` function.
# Conversion to and from JsObject # Conversion to and from JsObject
proc to*(x: JsObject, T: typedesc): T {.importcpp: "(#)".} proc to*(x: JsObject, T: typedesc): T {.importcpp: "(#)".}
## Converts a JsObject `x` to type `T`. ## Converts a JsObject `x` to type `T`.
proc toJs*[T](val: T): JsObject {.importcpp: "(#)".} proc toJs*[T](val: T): JsObject {.importcpp: "(#)".}
## Converts a value of any type to type JsObject ## Converts a value of any type to type JsObject.
template toJs*(s: string): JsObject = cstring(s).toJs template toJs*(s: string): JsObject = cstring(s).toJs
@ -161,7 +161,7 @@ macro jsFromAst*(n: untyped): untyped =
return quote: toJs(`result`) return quote: toJs(`result`)
proc `&`*(a, b: cstring): cstring {.importcpp: "(# + #)".} proc `&`*(a, b: cstring): cstring {.importcpp: "(# + #)".}
## Concatenation operator for JavaScript strings ## Concatenation operator for JavaScript strings.
proc `+` *(x, y: JsObject): JsObject {.importcpp: "(# + #)".} proc `+` *(x, y: JsObject): JsObject {.importcpp: "(# + #)".}
proc `-` *(x, y: JsObject): JsObject {.importcpp: "(# - #)".} proc `-` *(x, y: JsObject): JsObject {.importcpp: "(# - #)".}
@ -186,24 +186,24 @@ proc `not`*(x: JsObject): JsObject {.importcpp: "(!#)".}
proc `in` *(x, y: JsObject): JsObject {.importcpp: "(# in #)".} proc `in` *(x, y: JsObject): JsObject {.importcpp: "(# in #)".}
proc `[]`*(obj: JsObject, field: cstring): JsObject {.importcpp: getImpl.} proc `[]`*(obj: JsObject, field: cstring): JsObject {.importcpp: getImpl.}
## Return the value of a property of name `field` from a JsObject `obj`. ## Returns the value of a property of name `field` from a JsObject `obj`.
proc `[]`*(obj: JsObject, field: int): JsObject {.importcpp: getImpl.} proc `[]`*(obj: JsObject, field: int): JsObject {.importcpp: getImpl.}
## Return the value of a property of name `field` from a JsObject `obj`. ## Returns the value of a property of name `field` from a JsObject `obj`.
proc `[]=`*[T](obj: JsObject, field: cstring, val: T) {.importcpp: setImpl.} proc `[]=`*[T](obj: JsObject, field: cstring, val: T) {.importcpp: setImpl.}
## Set the value of a property of name `field` in a JsObject `obj` to `v`. ## Sets the value of a property of name `field` in a JsObject `obj` to `v`.
proc `[]=`*[T](obj: JsObject, field: int, val: T) {.importcpp: setImpl.} proc `[]=`*[T](obj: JsObject, field: int, val: T) {.importcpp: setImpl.}
## Set the value of a property of name `field` in a JsObject `obj` to `v`. ## Sets the value of a property of name `field` in a JsObject `obj` to `v`.
proc `[]`*[K: JsKey, V](obj: JsAssoc[K, V], field: K): V proc `[]`*[K: JsKey, V](obj: JsAssoc[K, V], field: K): V
{.importcpp: getImpl.} {.importcpp: getImpl.}
## Return the value of a property of name `field` from a JsAssoc `obj`. ## Returns the value of a property of name `field` from a JsAssoc `obj`.
proc `[]=`*[K: JsKey, V](obj: JsAssoc[K, V], field: K, val: V) proc `[]=`*[K: JsKey, V](obj: JsAssoc[K, V], field: K, val: V)
{.importcpp: setImpl.} {.importcpp: setImpl.}
## Set the value of a property of name `field` in a JsAssoc `obj` to `v`. ## Sets the value of a property of name `field` in a JsAssoc `obj` to `v`.
proc `[]`*[V](obj: JsAssoc[cstring, V], field: string): V = proc `[]`*[V](obj: JsAssoc[cstring, V], field: string): V =
obj[cstring(field)] obj[cstring(field)]
@ -212,7 +212,7 @@ proc `[]=`*[V](obj: JsAssoc[cstring, V], field: string, val: V) =
obj[cstring(field)] = val obj[cstring(field)] = val
proc `==`*(x, y: JsRoot): bool {.importcpp: "(# === #)".} proc `==`*(x, y: JsRoot): bool {.importcpp: "(# === #)".}
## Compare two JsObjects or JsAssocs. Be careful though, as this is comparison ## Compares two JsObjects or JsAssocs. Be careful though, as this is comparison
## like in JavaScript, so if your JsObjects are in fact JavaScript Objects, ## like in JavaScript, so if your JsObjects are in fact JavaScript Objects,
## and not strings or numbers, this is a *comparison of references*. ## and not strings or numbers, this is a *comparison of references*.
@ -341,7 +341,7 @@ macro `.()`*[K: cstring, V: proc](obj: JsAssoc[K, V],
# Iterators: # Iterators:
iterator pairs*(obj: JsObject): (cstring, JsObject) = iterator pairs*(obj: JsObject): (cstring, JsObject) =
## Yields tuples of type ``(cstring, JsObject)``, with the first entry ## Yields tuples of type `(cstring, JsObject)`, with the first entry
## being the `name` of a fields in the JsObject and the second being its ## being the `name` of a fields in the JsObject and the second being its
## value wrapped into a JsObject. ## value wrapped into a JsObject.
var k: cstring var k: cstring
@ -370,7 +370,7 @@ iterator keys*(obj: JsObject): cstring =
{.emit: "}".} {.emit: "}".}
iterator pairs*[K: JsKey, V](assoc: JsAssoc[K, V]): (K,V) = iterator pairs*[K: JsKey, V](assoc: JsAssoc[K, V]): (K,V) =
## Yields tuples of type ``(K, V)``, with the first entry ## Yields tuples of type `(K, V)`, with the first entry
## being a `key` in the JsAssoc and the second being its corresponding value. ## being a `key` in the JsAssoc and the second being its corresponding value.
var k: cstring var k: cstring
var v: V var v: V
@ -400,16 +400,16 @@ iterator keys*[K: JsKey, V](assoc: JsAssoc[K, V]): K =
# Literal generation # Literal generation
macro `{}`*(typ: typedesc, xs: varargs[untyped]): auto = macro `{}`*(typ: typedesc, xs: varargs[untyped]): auto =
## Takes a ``typedesc`` as its first argument, and a series of expressions of ## Takes a `typedesc` as its first argument, and a series of expressions of
## type ``key: value``, and returns a value of the specified type with each ## type `key: value`, and returns a value of the specified type with each
## field ``key`` set to ``value``, as specified in the arguments of ``{}``. ## field `key` set to `value`, as specified in the arguments of `{}`.
## ##
## Example: ## Example:
## ##
## .. code-block:: nim ## .. code-block:: nim
## ##
## # Let's say we have a type with a ton of fields, where some fields do not ## # Let's say we have a type with a ton of fields, where some fields do not
## # need to be set, and we do not want those fields to be set to ``nil``: ## # need to be set, and we do not want those fields to be set to `nil`:
## type ## type
## ExtremelyHugeType = ref object ## ExtremelyHugeType = ref object
## a, b, c, d, e, f, g: int ## a, b, c, d, e, f, g: int
@ -464,7 +464,7 @@ proc replaceSyms(n: NimNode): NimNode =
macro bindMethod*(procedure: typed): auto = macro bindMethod*(procedure: typed): auto =
## Takes the name of a procedure and wraps it into a lambda missing the first ## Takes the name of a procedure and wraps it into a lambda missing the first
## argument, which passes the JavaScript builtin ``this`` as the first ## argument, which passes the JavaScript builtin `this` as the first
## argument to the procedure. Returns the resulting lambda. ## argument to the procedure. Returns the resulting lambda.
## ##
## Example: ## Example:
@ -477,7 +477,7 @@ macro bindMethod*(procedure: typed): auto =
## return this.a + 42; ## return this.a + 42;
## }; ## };
## ##
## We can achieve this using the ``bindMethod`` macro: ## We can achieve this using the `bindMethod` macro:
## ##
## .. code-block:: nim ## .. code-block:: nim
## let obj = JsObject{ a: 10 } ## let obj = JsObject{ a: 10 }

2
lib/js/jsre.nim
View file

@ -11,7 +11,7 @@ runnableExamples:
doAssert jsregex.test(r"0123456789abcd") doAssert jsregex.test(r"0123456789abcd")
when not defined(js) and not defined(Nimdoc): when not defined(js):
{.error: "This module only works on the JavaScript platform".} {.error: "This module only works on the JavaScript platform".}
type RegExp* {.importjs.} = object ## Regular Expressions for JavaScript target. type RegExp* {.importjs.} = object ## Regular Expressions for JavaScript target.

1
tools/kochdocs.nim
View file

@ -136,7 +136,6 @@ lib/wrappers/openssl.nim
lib/posix/posix.nim lib/posix/posix.nim
lib/posix/linux.nim lib/posix/linux.nim
lib/posix/termios.nim lib/posix/termios.nim
lib/js/jscore.nim
""".splitWhitespace() """.splitWhitespace()
# some of these are include files so shouldn't be docgen'd # some of these are include files so shouldn't be docgen'd