From 24d8eedd4c943b2cce03c283e9b8d198a9a9847e Mon Sep 17 00:00:00 2001 From: Tim Voronov Date: Fri, 7 Aug 2020 21:49:29 -0400 Subject: [PATCH] Feature/doc markup (#543) * Added release notes * #509 fixedOCOD typo * Updated values * Updated comments * Changed stdlib docs format * Changed format of array in docs * Use 'any' instead of 'value' in docs * New format for optional params * Updated docs for testing package * Added namespace information --- CHANGELOG.md | 15 ++++++++- pkg/stdlib/arrays/append.go | 8 ++--- pkg/stdlib/arrays/first.go | 6 ++-- pkg/stdlib/arrays/flatten.go | 8 ++--- pkg/stdlib/arrays/intersection.go | 6 ++-- pkg/stdlib/arrays/last.go | 6 ++-- pkg/stdlib/arrays/minus.go | 6 ++-- pkg/stdlib/arrays/nth.go | 8 ++--- pkg/stdlib/arrays/outersection.go | 6 ++-- pkg/stdlib/arrays/pop.go | 6 ++-- pkg/stdlib/arrays/position.go | 9 +++--- pkg/stdlib/arrays/push.go | 10 +++--- pkg/stdlib/arrays/remove_nth.go | 8 ++--- pkg/stdlib/arrays/remove_value.go | 10 +++--- pkg/stdlib/arrays/remove_values.go | 8 ++--- pkg/stdlib/arrays/shift.go | 6 ++-- pkg/stdlib/arrays/slice.go | 10 +++--- pkg/stdlib/arrays/sorted.go | 6 ++-- pkg/stdlib/arrays/sorted_unique.go | 6 ++-- pkg/stdlib/arrays/union.go | 6 ++-- pkg/stdlib/arrays/union_distinct.go | 3 ++ pkg/stdlib/arrays/union_test.go | 4 +-- pkg/stdlib/arrays/unique.go | 6 ++-- pkg/stdlib/arrays/unshift.go | 11 +++---- pkg/stdlib/collections/include.go | 8 ++--- pkg/stdlib/collections/length.go | 3 ++ pkg/stdlib/collections/reverse.go | 6 ++-- pkg/stdlib/datetime/add_subtract.go | 18 +++++------ pkg/stdlib/datetime/compare.go | 12 +++---- pkg/stdlib/datetime/date.go | 6 ++-- pkg/stdlib/datetime/day.go | 4 +-- pkg/stdlib/datetime/dayofweek.go | 4 +-- pkg/stdlib/datetime/dayofyear.go | 4 +-- pkg/stdlib/datetime/daysinmonth.go | 4 +-- pkg/stdlib/datetime/diff.go | 10 +++--- pkg/stdlib/datetime/format.go | 4 +-- pkg/stdlib/datetime/hour.go | 4 +-- pkg/stdlib/datetime/leapyear.go | 4 +-- pkg/stdlib/datetime/millisecond.go | 4 +-- pkg/stdlib/datetime/minute.go | 4 +-- pkg/stdlib/datetime/month.go | 4 +-- pkg/stdlib/datetime/now.go | 2 +- pkg/stdlib/datetime/quarter.go | 4 +-- pkg/stdlib/datetime/second.go | 4 +-- pkg/stdlib/datetime/year.go | 4 +-- pkg/stdlib/html/attr_get.go | 6 ++-- pkg/stdlib/html/attr_remove.go | 4 +-- pkg/stdlib/html/attr_set.go | 6 ++-- pkg/stdlib/html/blur.go | 4 +-- pkg/stdlib/html/clear.go | 4 +-- pkg/stdlib/html/click.go | 6 ++-- pkg/stdlib/html/click_all.go | 8 ++--- pkg/stdlib/html/cookie_del.go | 4 +-- pkg/stdlib/html/cookie_get.go | 5 +-- pkg/stdlib/html/cookie_set.go | 4 +-- pkg/stdlib/html/document.go | 24 ++++++++------ pkg/stdlib/html/download.go | 4 +-- pkg/stdlib/html/element.go | 6 ++-- pkg/stdlib/html/element_exists.go | 6 ++-- pkg/stdlib/html/elements.go | 6 ++-- pkg/stdlib/html/elements_count.go | 6 ++-- pkg/stdlib/html/find_frames.go | 8 ++--- pkg/stdlib/html/focus.go | 4 +-- pkg/stdlib/html/get_inner_html.go | 6 ++-- pkg/stdlib/html/get_inner_html_all.go | 6 ++-- pkg/stdlib/html/get_inner_text.go | 6 ++-- pkg/stdlib/html/get_inner_text_all.go | 6 ++-- pkg/stdlib/html/hover.go | 4 +-- pkg/stdlib/html/input.go | 10 +++--- pkg/stdlib/html/mouse_xy.go | 6 ++-- pkg/stdlib/html/navigate.go | 6 ++-- pkg/stdlib/html/navigate_back.go | 8 ++--- pkg/stdlib/html/navigate_forward.go | 8 ++--- pkg/stdlib/html/pagination.go | 4 +-- pkg/stdlib/html/parse.go | 21 +++++++----- pkg/stdlib/html/pdf.go | 36 ++++++++++----------- pkg/stdlib/html/screenshot.go | 18 +++++------ pkg/stdlib/html/scroll_bottom.go | 9 ++++-- pkg/stdlib/html/scroll_element.go | 9 ++++-- pkg/stdlib/html/scroll_top.go | 9 ++++-- pkg/stdlib/html/scroll_xy.go | 11 ++++--- pkg/stdlib/html/select.go | 8 ++--- pkg/stdlib/html/set_inner_html.go | 6 ++-- pkg/stdlib/html/set_inner_text.go | 6 ++-- pkg/stdlib/html/style_get.go | 6 ++-- pkg/stdlib/html/style_remove.go | 4 +-- pkg/stdlib/html/style_set.go | 6 ++-- pkg/stdlib/html/wait_attr.go | 20 ++++++------ pkg/stdlib/html/wait_attr_all.go | 16 +++++----- pkg/stdlib/html/wait_class.go | 22 +++++-------- pkg/stdlib/html/wait_class_all.go | 16 +++++----- pkg/stdlib/html/wait_element.go | 12 +++---- pkg/stdlib/html/wait_navigation.go | 4 +-- pkg/stdlib/html/wait_style.go | 14 ++++++-- pkg/stdlib/html/wait_style_all.go | 14 ++++++-- pkg/stdlib/html/xpath.go | 6 ++-- pkg/stdlib/io/fs/lib.go | 1 + pkg/stdlib/io/fs/read.go | 6 ++-- pkg/stdlib/io/fs/write.go | 18 +++++------ pkg/stdlib/io/lib.go | 1 + pkg/stdlib/io/net/http/delete.go | 9 +++--- pkg/stdlib/io/net/http/get.go | 7 ++-- pkg/stdlib/io/net/http/lib.go | 1 + pkg/stdlib/io/net/http/post.go | 9 +++--- pkg/stdlib/io/net/http/put.go | 9 +++--- pkg/stdlib/io/net/http/request.go | 11 ++++--- pkg/stdlib/io/net/lib.go | 1 + pkg/stdlib/math/abs.go | 6 ++-- pkg/stdlib/math/acos.go | 6 ++-- pkg/stdlib/math/asin.go | 6 ++-- pkg/stdlib/math/atan.go | 6 ++-- pkg/stdlib/math/atan2.go | 8 ++--- pkg/stdlib/math/average.go | 6 ++-- pkg/stdlib/math/ceil.go | 6 ++-- pkg/stdlib/math/cos.go | 6 ++-- pkg/stdlib/math/degrees.go | 6 ++-- pkg/stdlib/math/exp.go | 6 ++-- pkg/stdlib/math/exp2.go | 6 ++-- pkg/stdlib/math/floor.go | 6 ++-- pkg/stdlib/math/log.go | 6 ++-- pkg/stdlib/math/log10.go | 6 ++-- pkg/stdlib/math/log2.go | 6 ++-- pkg/stdlib/math/max.go | 6 ++-- pkg/stdlib/math/median.go | 6 ++-- pkg/stdlib/math/min.go | 6 ++-- pkg/stdlib/math/percentile.go | 10 +++--- pkg/stdlib/math/pi.go | 4 +-- pkg/stdlib/math/pow.go | 8 ++--- pkg/stdlib/math/radians.go | 6 ++-- pkg/stdlib/math/rand.go | 8 ++--- pkg/stdlib/math/range.go | 9 +++--- pkg/stdlib/math/round.go | 6 ++-- pkg/stdlib/math/sin.go | 6 ++-- pkg/stdlib/math/sqrt.go | 6 ++-- pkg/stdlib/math/stddev_population.go | 6 ++-- pkg/stdlib/math/stddev_sample.go | 6 ++-- pkg/stdlib/math/sum.go | 6 ++-- pkg/stdlib/math/tan.go | 6 ++-- pkg/stdlib/math/variance_population.go | 6 ++-- pkg/stdlib/math/variance_sample.go | 6 ++-- pkg/stdlib/objects/has.go | 6 ++-- pkg/stdlib/objects/keep_keys.go | 8 ++--- pkg/stdlib/objects/keys.go | 8 ++--- pkg/stdlib/objects/merge.go | 6 ++-- pkg/stdlib/objects/merge_recursive.go | 6 ++-- pkg/stdlib/objects/values.go | 6 ++-- pkg/stdlib/objects/zip.go | 8 ++--- pkg/stdlib/path/base.go | 7 ++-- pkg/stdlib/path/clean.go | 6 ++-- pkg/stdlib/path/dir.go | 6 ++-- pkg/stdlib/path/ext.go | 6 ++-- pkg/stdlib/path/is_abs.go | 6 ++-- pkg/stdlib/path/join.go | 6 ++-- pkg/stdlib/path/lib.go | 1 + pkg/stdlib/path/match.go | 8 ++--- pkg/stdlib/path/separate.go | 6 ++-- pkg/stdlib/strings/case.go | 12 +++---- pkg/stdlib/strings/concat.go | 14 ++++---- pkg/stdlib/strings/contains.go | 11 +++---- pkg/stdlib/strings/decode.go | 12 +++---- pkg/stdlib/strings/encode.go | 30 +++++++++--------- pkg/stdlib/strings/escape.go | 6 ++-- pkg/stdlib/strings/find.go | 26 +++++++-------- pkg/stdlib/strings/fmt.go | 8 ++--- pkg/stdlib/strings/json.go | 12 +++---- pkg/stdlib/strings/lib.go | 4 --- pkg/stdlib/strings/like.go | 10 +++--- pkg/stdlib/strings/random.go | 6 ++-- pkg/stdlib/strings/regex.go | 44 +++++++++++++------------- pkg/stdlib/strings/split.go | 10 +++--- pkg/stdlib/strings/substitute.go | 12 +++---- pkg/stdlib/strings/substr.go | 26 +++++++-------- pkg/stdlib/strings/trim.go | 24 +++++++------- pkg/stdlib/strings/unescape.go | 6 ++-- pkg/stdlib/testing/array.go | 6 ++-- pkg/stdlib/testing/binary.go | 6 ++-- pkg/stdlib/testing/datetime.go | 6 ++-- pkg/stdlib/testing/empty.go | 6 ++-- pkg/stdlib/testing/equal.go | 8 ++--- pkg/stdlib/testing/fail.go | 4 +-- pkg/stdlib/testing/false.go | 6 ++-- pkg/stdlib/testing/float.go | 6 ++-- pkg/stdlib/testing/gt.go | 8 ++--- pkg/stdlib/testing/gte.go | 8 ++--- pkg/stdlib/testing/include.go | 8 ++--- pkg/stdlib/testing/int.go | 6 ++-- pkg/stdlib/testing/len.go | 8 ++--- pkg/stdlib/testing/lib.go | 1 + pkg/stdlib/testing/lt.go | 8 ++--- pkg/stdlib/testing/lte.go | 8 ++--- pkg/stdlib/testing/match.go | 8 ++--- pkg/stdlib/testing/none.go | 6 ++-- pkg/stdlib/testing/object.go | 6 ++-- pkg/stdlib/testing/string.go | 6 ++-- pkg/stdlib/testing/true.go | 6 ++-- pkg/stdlib/types/is_array.go | 6 ++-- pkg/stdlib/types/is_binary.go | 6 ++-- pkg/stdlib/types/is_boolean.go | 6 ++-- pkg/stdlib/types/is_date_time.go | 6 ++-- pkg/stdlib/types/is_float.go | 6 ++-- pkg/stdlib/types/is_html_document.go | 6 ++-- pkg/stdlib/types/is_html_element.go | 6 ++-- pkg/stdlib/types/is_int.go | 6 ++-- pkg/stdlib/types/is_nan.go | 6 ++-- pkg/stdlib/types/is_none.go | 6 ++-- pkg/stdlib/types/is_object.go | 6 ++-- pkg/stdlib/types/is_string.go | 6 ++-- pkg/stdlib/types/to_array.go | 6 ++-- pkg/stdlib/types/to_boolean.go | 6 ++-- pkg/stdlib/types/to_date_time.go | 6 ++-- pkg/stdlib/types/to_float.go | 6 ++-- pkg/stdlib/types/to_int.go | 6 ++-- pkg/stdlib/types/to_string.go | 6 ++-- pkg/stdlib/types/type_name.go | 6 ++-- pkg/stdlib/utils/log.go | 3 +- pkg/stdlib/utils/wait.go | 4 +-- 216 files changed, 863 insertions(+), 801 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index fc2439f4..6b9738bb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,8 +1,21 @@ ## Changelog +### 0.12.0 +#### Added +- iframe navigation handling [#535](https://github.com/MontFerret/ferret/pull/535) +- Assertion library [#526](https://github.com/MontFerret/ferret/pull/526) + +#### Changed +- Removed property caching and tracking [#531](https://github.com/MontFerret/ferret/pull/531) +- Updated dependencies [#528](https://github.com/MontFerret/ferret/pull/528), [#525](https://github.com/MontFerret/ferret/pull/525) + +#### Fixed +- ``WAIT`` does not respect cancellation signal [#524](https://github.com/MontFerret/ferret/pull/524) +- Missed ``DATE_COMPARE`` [#537](https://github.com/MontFerret/ferret/pull/537) +- Spelling [#534](https://github.com/MontFerret/ferret/pull/534) + ### 0.11.1 #### Fixed - - Fixed use of unquoted scroll options [#521](https://github.com/MontFerret/ferret/pull/521) - Upgraded ANTLR version [#517](https://github.com/MontFerret/ferret/pull/517) diff --git a/pkg/stdlib/arrays/append.go b/pkg/stdlib/arrays/append.go index 6d60b4a5..26dd8101 100644 --- a/pkg/stdlib/arrays/append.go +++ b/pkg/stdlib/arrays/append.go @@ -8,11 +8,11 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// Append appends a new item to an array and returns a new array with a given element. +// APPEND appends a new item to an array and returns a new array with a given element. // If ``uniqueOnly`` is set to true, then will add the item only if it's unique. -// @param arr (Array) - Target array. -// @param item (Read) - Target value to add. -// @returns arr (Array) - New array. +// @param {Any[]} arr - Target array. +// @param {Any} item - Target value to add. +// @return {Any[]} - New array. func Append(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 2, 3) diff --git a/pkg/stdlib/arrays/first.go b/pkg/stdlib/arrays/first.go index 38977ef4..7cb0e4c2 100644 --- a/pkg/stdlib/arrays/first.go +++ b/pkg/stdlib/arrays/first.go @@ -8,9 +8,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// First returns a first element from a given array. -// @param arr (Array) - Target array. -// @returns element (Read) - First element in a given array. +// FIRST returns a first element from a given array. +// @param {Any[]} arr - Target array. +// @return {Any} - First element in a given array. func First(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/arrays/flatten.go b/pkg/stdlib/arrays/flatten.go index fdc13fc3..45172154 100644 --- a/pkg/stdlib/arrays/flatten.go +++ b/pkg/stdlib/arrays/flatten.go @@ -8,14 +8,14 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// Flatten turn an array of arrays into a flat array. +// FLATTEN turns an array of arrays into a flat array. // All array elements in array will be expanded in the result array. // Non-array elements are added as they are. // The function will recurse into sub-arrays up to the specified depth. // Duplicates will not be removed. -// @param arr (Array) - Target array. -// @param depth (Int, optional) - Depth level. -// @returns (Array) - Flat array. +// @param {Any[]} arr - Target array. +// @param {Int} [depth] - Depth level. +// @return {Any[]} - Flat array. func Flatten(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 2) diff --git a/pkg/stdlib/arrays/intersection.go b/pkg/stdlib/arrays/intersection.go index 0b8cb112..4e8fe4fe 100644 --- a/pkg/stdlib/arrays/intersection.go +++ b/pkg/stdlib/arrays/intersection.go @@ -8,11 +8,11 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// Intersection return the intersection of all arrays specified. +// INTERSECTION return the intersection of all arrays specified. // The result is an array of values that occur in all arguments. -// @param arrays (Array, repeated) - An arbitrary number of arrays as multiple arguments (at least 2). -// @returns (Array) - A single array with only the elements, which exist in all provided arrays. // The element order is random. Duplicates are removed. +// @param {Any[], repeated} arrays - An arbitrary number of arrays as multiple arguments (at least 2). +// @return {Any[]} - A single array with only the elements, which exist in all provided arrays. func Intersection(_ context.Context, args ...core.Value) (core.Value, error) { return sections(args, len(args)) } diff --git a/pkg/stdlib/arrays/last.go b/pkg/stdlib/arrays/last.go index 78fbef5c..fe2b01dc 100644 --- a/pkg/stdlib/arrays/last.go +++ b/pkg/stdlib/arrays/last.go @@ -8,9 +8,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// Last returns the last element of an array. -// @param array (Array) - The target array. -// @returns (Read) - Last element of an array. +// LAST returns the last element of an array. +// @param {Any[]} array - The target array. +// @return {Any} - Last element of an array. func Last(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/arrays/minus.go b/pkg/stdlib/arrays/minus.go index 6771dc6a..39506203 100644 --- a/pkg/stdlib/arrays/minus.go +++ b/pkg/stdlib/arrays/minus.go @@ -8,10 +8,10 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// Minus return the difference of all arrays specified. -// @param arrays (Array, repeated) - An arbitrary number of arrays as multiple arguments (at least 2). -// @returns array (Array) - An array of values that occur in the first array, but not in any of the subsequent arrays. +// MINUS return the difference of all arrays specified. // The order of the result array is undefined and should not be relied on. Duplicates will be removed. +// @param {Any[], repeated} arrays - An arbitrary number of arrays as multiple arguments (at least 2). +// @return {Any[]} - An array of values that occur in the first array, but not in any of the subsequent arrays. func Minus(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 2, core.MaxArgs) diff --git a/pkg/stdlib/arrays/nth.go b/pkg/stdlib/arrays/nth.go index 24679eec..dabace1f 100644 --- a/pkg/stdlib/arrays/nth.go +++ b/pkg/stdlib/arrays/nth.go @@ -8,12 +8,12 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// Nth returns the element of an array at a given position. +// NTH returns the element of an array at a given position. // It is the same as anyArray[position] for positive positions, but does not support negative positions. -// @param array (Array) - An array with elements of arbitrary type. -// @param index (Int) - Position of desired element in array, positions start at 0. -// @returns (Read) - The array element at the given position. // If position is negative or beyond the upper bound of the array, then NONE will be returned. +// @param {Any[]} array - An array with elements of arbitrary type. +// @param {Int} index - Position of desired element in array, positions start at 0. +// @return {Any} - The array element at the given position. func Nth(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 2, 2) diff --git a/pkg/stdlib/arrays/outersection.go b/pkg/stdlib/arrays/outersection.go index d7b2491e..b2ac5b00 100644 --- a/pkg/stdlib/arrays/outersection.go +++ b/pkg/stdlib/arrays/outersection.go @@ -6,10 +6,10 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/core" ) -// Outersection return the values that occur only once across all arrays specified. -// @param arrays (Array, repeated) - An arbitrary number of arrays as multiple arguments (at least 2). -// @returns (Array) - A single array with only the elements that exist only once across all provided arrays. +// OUTERSECTION return the values that occur only once across all arrays specified. // The element order is random. +// @param {Any[], repeated} arrays - An arbitrary number of arrays as multiple arguments (at least 2). +// @return {Any[]} - A single array with only the elements that exist only once across all provided arrays. func Outersection(_ context.Context, args ...core.Value) (core.Value, error) { return sections(args, 1) } diff --git a/pkg/stdlib/arrays/pop.go b/pkg/stdlib/arrays/pop.go index 8230bdfe..db0061b4 100644 --- a/pkg/stdlib/arrays/pop.go +++ b/pkg/stdlib/arrays/pop.go @@ -8,9 +8,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// Pop returns a new array without last element. -// @param array (Array) - Target array. -// @returns (Array) - Copy of an array without last element. +// POP returns a new array without last element. +// @param {Any[]} array - Target array. +// @return {Any[]} - Copy of an array without last element. func Pop(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/arrays/position.go b/pkg/stdlib/arrays/position.go index 01f1a3e9..302aaf4e 100644 --- a/pkg/stdlib/arrays/position.go +++ b/pkg/stdlib/arrays/position.go @@ -8,10 +8,11 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// Position returns a value indicating whether an element is contained in array. Optionally returns its position. -// @param array (Array) - The source array. -// @param value (Read) - The target value. -// @param returnIndex (Boolean, optional) - Read which indicates whether to return item's position. +// POSITION returns a value indicating whether an element is contained in array. Optionally returns its position. +// @param {Any[]} array - The source array. +// @param {Any} value - The target value. +// @param {Boolean} [position=False] - Boolean value which indicates whether to return item's position. +// @return {Boolean | Int} - A value indicating whether an element is contained in array. func Position(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 2, 3) diff --git a/pkg/stdlib/arrays/push.go b/pkg/stdlib/arrays/push.go index 9e9825cb..b60c8e45 100644 --- a/pkg/stdlib/arrays/push.go +++ b/pkg/stdlib/arrays/push.go @@ -8,11 +8,11 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// Push create a new array with appended value. -// @param array (Array) - Source array. -// @param value (Read) - Target value. -// @param unique (Boolean, optional) - Read indicating whether to do uniqueness check. -// @returns (Array) - A new array with appended value. +// PUSH create a new array with appended value. +// @param {Any[]} array - Source array. +// @param {Any} value - Target value. +// @param {Boolean} [unique=False] - Read indicating whether to do uniqueness check. +// @return {Any[]} - A new array with appended value. func Push(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 2, 3) diff --git a/pkg/stdlib/arrays/remove_nth.go b/pkg/stdlib/arrays/remove_nth.go index c559ee82..498d1d48 100644 --- a/pkg/stdlib/arrays/remove_nth.go +++ b/pkg/stdlib/arrays/remove_nth.go @@ -8,10 +8,10 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// RemoveNth returns a new array without an element by a given position. -// @param array (Array) - Source array. -// @param position (Int) - Target element position. -// @return (Array) - A new array without an element by a given position. +// REMOVE_NTH returns a new array without an element by a given position. +// @param {Any[]} array - Source array. +// @param {Int} position - Target element position. +// @return {Any[]} - A new array without an element by a given position. func RemoveNth(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 2, 2) diff --git a/pkg/stdlib/arrays/remove_value.go b/pkg/stdlib/arrays/remove_value.go index 5ede00d1..8a0babdf 100644 --- a/pkg/stdlib/arrays/remove_value.go +++ b/pkg/stdlib/arrays/remove_value.go @@ -8,12 +8,12 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// RemoveValue returns a new array with removed all occurrences of value in a given array. +// REMOVE_VALUE returns a new array with removed all occurrences of value in a given array. // Optionally with a limit to the number of removals. -// @param array (Array) - Source array. -// @param value (Read) - Target value. -// @param limit (Int, optional) - A limit to the number of removals. -// @returns (Array) - A new array with removed all occurrences of value in a given array. +// @param {Any[]} array - Source array. +// @param {Any} value - Target value. +// @param {Int} [limit] - A limit to the number of removals. +// @return {Any[]} - A new array with removed all occurrences of value in a given array. func RemoveValue(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 2, 3) diff --git a/pkg/stdlib/arrays/remove_values.go b/pkg/stdlib/arrays/remove_values.go index c89a8e99..df71ab13 100644 --- a/pkg/stdlib/arrays/remove_values.go +++ b/pkg/stdlib/arrays/remove_values.go @@ -8,10 +8,10 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// RemoveValues returns a new array with removed all occurrences of values in a given array. -// @param array (Array) - Source array. -// @param values (Array) - Target values. -// @returns (Array) - A new array with removed all occurrences of values in a given array. +// REMOVE_VALUES returns a new array with removed all occurrences of values in a given array. +// @param {Any[]} array - Source array. +// @param {Any[]} values - Target values. +// @return {Any[]} - A new array with removed all occurrences of values in a given array. func RemoveValues(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 2, 2) diff --git a/pkg/stdlib/arrays/shift.go b/pkg/stdlib/arrays/shift.go index 56593928..f2aa9e7f 100644 --- a/pkg/stdlib/arrays/shift.go +++ b/pkg/stdlib/arrays/shift.go @@ -8,9 +8,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// Shift returns a new array without the first element. -// @param array (Array) - Target array. -// @returns (Array) - Copy of an array without the first element. +// SHIFT returns a new array without the first element. +// @param {Any[]} array - Target array. +// @return {Any[]} - Copy of an array without the first element. func Shift(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/arrays/slice.go b/pkg/stdlib/arrays/slice.go index 945a33bd..e6cb709d 100644 --- a/pkg/stdlib/arrays/slice.go +++ b/pkg/stdlib/arrays/slice.go @@ -8,11 +8,11 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// Slice returns a new sliced array. -// @param array (Array) - Source array. -// @param start (Int) - Start position of extraction. -// @param length (Int, optional) - Read indicating how many elements to extract. -// @returns (Array) - Sliced array. +// SLICE returns a new sliced array. +// @param {Any[]} array - Source array. +// @param {Int} start - Start position of extraction. +// @param {Int} [length] - Read indicating how many elements to extract. +// @return {Any[]} - Sliced array. func Slice(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 2, 3) diff --git a/pkg/stdlib/arrays/sorted.go b/pkg/stdlib/arrays/sorted.go index a769956c..8159ee42 100644 --- a/pkg/stdlib/arrays/sorted.go +++ b/pkg/stdlib/arrays/sorted.go @@ -8,10 +8,10 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// Sorted sorts all elements in anyArray. +// SORTED sorts all elements in anyArray. // The function will use the default comparison order for FQL value types. -// @param array (Array) - Target array. -// @returns (Array) - Sorted array. +// @param {Any[]} array - Target array. +// @return {Any[]} - Sorted array. func Sorted(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/arrays/sorted_unique.go b/pkg/stdlib/arrays/sorted_unique.go index cb7645f6..e188877f 100644 --- a/pkg/stdlib/arrays/sorted_unique.go +++ b/pkg/stdlib/arrays/sorted_unique.go @@ -8,11 +8,11 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// SortedUnique sorts all elements in anyArray. +// SORTED_UNIQUE sorts all elements in anyArray. // The function will use the default comparison order for FQL value types. // Additionally, the values in the result array will be made unique -// @param array (Array) - Target array. -// @returns (Array) - Sorted array. +// @param {Any[]} array - Target array. +// @return {Any[]} - Sorted array. func SortedUnique(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/arrays/union.go b/pkg/stdlib/arrays/union.go index 393ffb53..0a570c2d 100644 --- a/pkg/stdlib/arrays/union.go +++ b/pkg/stdlib/arrays/union.go @@ -8,9 +8,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// Union returns the union of all passed arrays. -// @param arrays (Array, repeated) - List of arrays to combine. -// @returns (Array) - All array elements combined in a single array, in any order. +// UNION returns the union of all passed arrays. +// @param {Any[], repeated} arrays - List of arrays to combine. +// @return {Any[]} - All array elements combined in a single array, in any order. func Union(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 2, core.MaxArgs) diff --git a/pkg/stdlib/arrays/union_distinct.go b/pkg/stdlib/arrays/union_distinct.go index a1634aed..3a73981a 100644 --- a/pkg/stdlib/arrays/union_distinct.go +++ b/pkg/stdlib/arrays/union_distinct.go @@ -8,6 +8,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) +// UNION_DISTINCT returns the union of all passed arrays with unique values. +// @param {Any[], repeated} arrays - List of arrays to combine. +// @return {Any[]} - All unique array elements combined in a single array, in any order. func UnionDistinct(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 2, core.MaxArgs) diff --git a/pkg/stdlib/arrays/union_test.go b/pkg/stdlib/arrays/union_test.go index 707c6f77..7387e827 100644 --- a/pkg/stdlib/arrays/union_test.go +++ b/pkg/stdlib/arrays/union_test.go @@ -10,8 +10,8 @@ import ( ) // TestUnion returns the union of distinct values of all passed arrays. -// @param arrays (Array, repeated) - List of arrays to combine. -// @returns (Array) - All array elements combined in a single array, without duplicates, in any order. +// @param arrays {Any[], repeated} - List of arrays to combine. +// @return {Any[]} - All array elements combined in a single array, without duplicates, in any order. func TestUnion(t *testing.T) { Convey("Should union all arrays", t, func() { arr1 := values.NewArrayWith( diff --git a/pkg/stdlib/arrays/unique.go b/pkg/stdlib/arrays/unique.go index 32018fc5..40f0c59f 100644 --- a/pkg/stdlib/arrays/unique.go +++ b/pkg/stdlib/arrays/unique.go @@ -8,9 +8,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// Unique returns all unique elements from a given array. -// @param array (Array) - Target array. -// @returns (Array) - New array without duplicates. +// UNIQUE returns all unique elements from a given array. +// @param {Any[]} array - Target array. +// @return {Any[]} - New array without duplicates. func Unique(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/arrays/unshift.go b/pkg/stdlib/arrays/unshift.go index b4d59db9..c461878f 100644 --- a/pkg/stdlib/arrays/unshift.go +++ b/pkg/stdlib/arrays/unshift.go @@ -8,12 +8,11 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// Unshift prepends value to a given array. -// @param array (Array) - Target array. -// @param value (Read) - Target value to prepend. -// @param unique (Boolean, optional) - Optional value indicating whether a value must be unique to be prepended. -// Default is false. -// @returns (Array) - New array with prepended value. +// UNSHIFT prepends value to a given array. +// @param {Any[]} array - Target array. +// @param {Any} value - Target value to prepend. +// @param {Boolean} [unique=False] - Optional value indicating whether a value must be unique to be prepended. Default is false. +// @return {Any[]} - New array with prepended value. func Unshift(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 2, 3) diff --git a/pkg/stdlib/collections/include.go b/pkg/stdlib/collections/include.go index bc9f7cc5..d0fb44df 100644 --- a/pkg/stdlib/collections/include.go +++ b/pkg/stdlib/collections/include.go @@ -8,10 +8,10 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// Includes checks whether a container includes a given value. -// @param text (String|Array|Object|Iterable) - The value container. -// @param text (Mixed) - The target value to assert. -// @returns (Boolean) - Returns a boolean value that indicates whether a container contains a given value. +// INCLUDES checks whether a container includes a given value. +// @param {String | Any[] | Object | Iterable} haystack - The value container. +// @param {Any} needle - The target value to assert. +// @return {Boolean} - A boolean value that indicates whether a container contains a given value. func Includes(ctx context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 2, 2) diff --git a/pkg/stdlib/collections/length.go b/pkg/stdlib/collections/length.go index 94994ba8..5bc75cc7 100644 --- a/pkg/stdlib/collections/length.go +++ b/pkg/stdlib/collections/length.go @@ -9,6 +9,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) +// LENGTH returns the length of a measurable value. +// @param {Measurable} value - The value to measure. +// @return {Int} - The length of the value. func Length(_ context.Context, inputs ...core.Value) (core.Value, error) { err := core.ValidateArgs(inputs, 1, 1) diff --git a/pkg/stdlib/collections/reverse.go b/pkg/stdlib/collections/reverse.go index a07af10f..cc1bdc3a 100644 --- a/pkg/stdlib/collections/reverse.go +++ b/pkg/stdlib/collections/reverse.go @@ -8,9 +8,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values" ) -// Reverse returns the reverse of a given string or array value. -// @param text (String|Array) - The string or array to reverse. -// @returns (String|Array) - Returns a reversed version of a given value. +// REVERSE returns the reverse of a given string or array value. +// @param {String | Any[]} value - The string or array to reverse. +// @return {String | Any[]} - A reversed version of a given value. func Reverse(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/datetime/add_subtract.go b/pkg/stdlib/datetime/add_subtract.go index f208b157..f9ec280a 100644 --- a/pkg/stdlib/datetime/add_subtract.go +++ b/pkg/stdlib/datetime/add_subtract.go @@ -14,11 +14,7 @@ var ( emptyString values.String ) -// DATE_ADD add amount given in unit to date. -// @params date (DateTime) - source date. -// @params amount (Int) - amount of units -// @params unit (String) - unit. -// @return (DateTime) - calculated date. +// DATE_ADD adds amount given in unit to date. // The following units are available: // * y, year, year // * m, month, months @@ -28,6 +24,10 @@ var ( // * i, minute, minutes // * s, second, seconds // * f, millisecond, milliseconds +// @param {DateTime} date - Source date. +// @param {Int} amount - Amount of units +// @param {String} unit - Unit. +// @return {DateTime} - Calculated date. func DateAdd(_ context.Context, args ...core.Value) (core.Value, error) { date, amount, unit, err := getArgs(args) if err != nil { @@ -45,10 +45,6 @@ func DateAdd(_ context.Context, args ...core.Value) (core.Value, error) { } // DATE_SUBTRACT subtract amount given in unit to date. -// @params date (DateTime) - source date. -// @params amount (Int) - amount of units -// @params unit (String) - unit. -// @return (DateTime) - calculated date. // The following units are available: // * y, year, year // * m, month, months @@ -58,6 +54,10 @@ func DateAdd(_ context.Context, args ...core.Value) (core.Value, error) { // * i, minute, minutes // * s, second, seconds // * f, millisecond, milliseconds +// @param {DateTime} date - source date. +// @param {Int} amount - amount of units +// @param {String} unit - unit. +// @return {DateTime} - calculated date. func DateSubtract(_ context.Context, args ...core.Value) (core.Value, error) { date, amount, unit, err := getArgs(args) if err != nil { diff --git a/pkg/stdlib/datetime/compare.go b/pkg/stdlib/datetime/compare.go index 89b37662..5cf6c893 100644 --- a/pkg/stdlib/datetime/compare.go +++ b/pkg/stdlib/datetime/compare.go @@ -9,12 +9,12 @@ import ( "github.com/pkg/errors" ) -// DATE_COMPARE check if two partial dates match. -// @params date1, date2 (DateTime) - comparable dates. -// @params unitRangeStart (String) - unit to start from. -// @params unitRangeEnd (String, Optional) - unit to end with. -// Error will be returned if unitRangeStart unit less that unitRangeEnd. -// @return (Boolean) - true if the dates match, else false. +// DATE_COMPARE checks if two partial dates match. +// @param {DateTime} date1 - First date. +// @param {DateTime} date2 - Second date. +// @param {String} unitRangeStart - Unit to start from. +// @param {String} [unitRangeEnd="millisecond"] - Unit to end with. Error will be returned if unitRangeStart unit less that unitRangeEnd. +// @return {Boolean} - True if the dates match, else false. func DateCompare(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 3, 4) if err != nil { diff --git a/pkg/stdlib/datetime/date.go b/pkg/stdlib/datetime/date.go index 9df26f24..e8def864 100644 --- a/pkg/stdlib/datetime/date.go +++ b/pkg/stdlib/datetime/date.go @@ -9,9 +9,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// DATE convert RFC3339 date time string to DateTime object. -// @params timeString (String) - string in RFC3339 format. -// @return (DateTime) - new DateTime object derived from timeString. +// DATE converts RFC3339 date time string to DateTime object. +// @param {String} time - String in RFC3339 format. +// @return {DateTime} - New DateTime object derived from timeString. func Date(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) if err != nil { diff --git a/pkg/stdlib/datetime/day.go b/pkg/stdlib/datetime/day.go index ed039542..d1855dc5 100644 --- a/pkg/stdlib/datetime/day.go +++ b/pkg/stdlib/datetime/day.go @@ -9,8 +9,8 @@ import ( ) // DATE_DAY returns the day of date as a number. -// @params date (DateTime) - source DateTime. -// @return (Int) - a day number. +// @param {DateTime} date - Source DateTime. +// @return {Int} - A day number. func DateDay(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) if err != nil { diff --git a/pkg/stdlib/datetime/dayofweek.go b/pkg/stdlib/datetime/dayofweek.go index 6722fdca..ef1eee4d 100644 --- a/pkg/stdlib/datetime/dayofweek.go +++ b/pkg/stdlib/datetime/dayofweek.go @@ -9,8 +9,8 @@ import ( ) // DATE_DAYOFWEEK returns number of the weekday from the date. Sunday is the 0th day of week. -// @params date (DateTime) - source DateTime. -// @return (Int) - return number of the weekday. +// @param {DateTime} date - Source DateTime. +// @return {Int} - Number of the weekday. func DateDayOfWeek(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) if err != nil { diff --git a/pkg/stdlib/datetime/dayofyear.go b/pkg/stdlib/datetime/dayofyear.go index f0fa70ff..9be9c3bd 100644 --- a/pkg/stdlib/datetime/dayofyear.go +++ b/pkg/stdlib/datetime/dayofyear.go @@ -10,8 +10,8 @@ import ( // DATE_DAYOFYEAR returns the day of year number of date. // The return value range from 1 to 365 (366 in a leap year). -// @params date (DateTime) - source DateTime. -// @return (Int) - a day of year number. +// @param {DateTime} date - Source DateTime. +// @return {Int} - A day of year number. func DateDayOfYear(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) if err != nil { diff --git a/pkg/stdlib/datetime/daysinmonth.go b/pkg/stdlib/datetime/daysinmonth.go index 7e9f15ad..2df51c9c 100644 --- a/pkg/stdlib/datetime/daysinmonth.go +++ b/pkg/stdlib/datetime/daysinmonth.go @@ -25,8 +25,8 @@ var daysCount = map[time.Month]int{ } // DATE_DAYS_IN_MONTH returns the number of days in the month of date. -// @params date (DateTime) - source DateTime. -// @return (Int) - number of the days. +// @param {DateTime} date - Source DateTime. +// @return {Int} - Number of the days. func DateDaysInMonth(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) if err != nil { diff --git a/pkg/stdlib/datetime/diff.go b/pkg/stdlib/datetime/diff.go index 5f9986d5..817f7a59 100644 --- a/pkg/stdlib/datetime/diff.go +++ b/pkg/stdlib/datetime/diff.go @@ -9,11 +9,11 @@ import ( ) // DATE_DIFF returns the difference between two dates in given time unit. -// @params date1 (DateTime) - first DateTime. -// @params date2 (DateTime) - second DateTime. -// @params unit (String) - time unit to return the difference in. -// @params asFloat (Boolean, optional) - if true amount of unit will be as float. -// @return (Int, Float) - difference between date1 and date2. +// @param {DateTime} date1 - First date. +// @param {DateTime} date2 - Second date. +// @param {String} unit - Time unit to return the difference in. +// @param {Boolean} [asFloat=False] - If true amount of unit will be as float. +// @return {Int | Float} - Difference between date1 and date2. func DateDiff(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 3, 4) if err != nil { diff --git a/pkg/stdlib/datetime/format.go b/pkg/stdlib/datetime/format.go index 2f43e686..68e4f76e 100644 --- a/pkg/stdlib/datetime/format.go +++ b/pkg/stdlib/datetime/format.go @@ -9,8 +9,8 @@ import ( ) // DATE_FORMAT format date according to the given format string. -// @params date (DateTime) - source DateTime object. -// @return (String) - formatted date. +// @param {DateTime} date - Source DateTime object. +// @return {String} - Formatted date. func DateFormat(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 2, 2) if err != nil { diff --git a/pkg/stdlib/datetime/hour.go b/pkg/stdlib/datetime/hour.go index af2e7168..7dac0798 100644 --- a/pkg/stdlib/datetime/hour.go +++ b/pkg/stdlib/datetime/hour.go @@ -9,8 +9,8 @@ import ( ) // DATE_HOUR returns the hour of date as a number. -// @params date (DateTime) - source DateTime. -// @return (Int) - a hour number. +// @param {DateTime} date - Source DateTime. +// @return {Int} - An hour number. func DateHour(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) if err != nil { diff --git a/pkg/stdlib/datetime/leapyear.go b/pkg/stdlib/datetime/leapyear.go index 93c3a6f0..c3efaa58 100644 --- a/pkg/stdlib/datetime/leapyear.go +++ b/pkg/stdlib/datetime/leapyear.go @@ -9,8 +9,8 @@ import ( ) // DATE_LEAPYEAR returns true if date is in a leap year else false. -// @params date (DateTime) - source DateTime. -// @return (Boolean) - date is in a leap year. +// @param {DateTime} date - Source DateTime. +// @return {Boolean} - Date is in a leap year. func DateLeapYear(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) if err != nil { diff --git a/pkg/stdlib/datetime/millisecond.go b/pkg/stdlib/datetime/millisecond.go index 7b3825a4..02c45ccd 100644 --- a/pkg/stdlib/datetime/millisecond.go +++ b/pkg/stdlib/datetime/millisecond.go @@ -9,8 +9,8 @@ import ( ) // DATE_MILLISECOND returns the millisecond of date as a number. -// @params date (DateTime) - source DateTime. -// @return (Int) - a millisecond number. +// @param {DateTime} date - Source DateTime. +// @return {Int} - A millisecond number. func DateMillisecond(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) if err != nil { diff --git a/pkg/stdlib/datetime/minute.go b/pkg/stdlib/datetime/minute.go index f5a71ec6..4a96d93a 100644 --- a/pkg/stdlib/datetime/minute.go +++ b/pkg/stdlib/datetime/minute.go @@ -9,8 +9,8 @@ import ( ) // DATE_MINUTE returns the minute of date as a number. -// @params date (DateTime) - source DateTime. -// @return (Int) - a minute number. +// @param {DateTime} date -Source DateTime. +// @return {Int} - A minute number. func DateMinute(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) if err != nil { diff --git a/pkg/stdlib/datetime/month.go b/pkg/stdlib/datetime/month.go index 33f9b0c5..cd6c533a 100644 --- a/pkg/stdlib/datetime/month.go +++ b/pkg/stdlib/datetime/month.go @@ -9,8 +9,8 @@ import ( ) // DATE_MONTH returns the month of date as a number. -// @params date (DateTime) - source DateTime. -// @return (Int) - a month number. +// @param {DateTime} date - Source DateTime. +// @return {Int} - A month number. func DateMonth(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) if err != nil { diff --git a/pkg/stdlib/datetime/now.go b/pkg/stdlib/datetime/now.go index d41b597f..2cdd90a5 100644 --- a/pkg/stdlib/datetime/now.go +++ b/pkg/stdlib/datetime/now.go @@ -9,7 +9,7 @@ import ( ) // NOW returns new DateTime object with Time equal to time.Now(). -// @returns (DateTime) - New DateTime object. +// @return {DateTime} - New DateTime object. func Now(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 0, 0) if err != nil { diff --git a/pkg/stdlib/datetime/quarter.go b/pkg/stdlib/datetime/quarter.go index 42296a58..b08725b3 100644 --- a/pkg/stdlib/datetime/quarter.go +++ b/pkg/stdlib/datetime/quarter.go @@ -10,8 +10,8 @@ import ( ) // DATE_QUARTER returns which quarter date belongs to. -// @params date (DateTime) - source DateTime. -// @return (Int) - a quarter number. +// @param {DateTime} date - Source DateTime. +// @return {Int} - A quarter number. func DateQuarter(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) if err != nil { diff --git a/pkg/stdlib/datetime/second.go b/pkg/stdlib/datetime/second.go index 9dbfca8c..84fb559c 100644 --- a/pkg/stdlib/datetime/second.go +++ b/pkg/stdlib/datetime/second.go @@ -9,8 +9,8 @@ import ( ) // DATE_SECOND returns the second of date as a number. -// @params date (DateTime) - source DateTime. -// @return (Int) - a second number. +// @param {DateTime} date - Source DateTime. +// @return {Int} - A second number. func DateSecond(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) if err != nil { diff --git a/pkg/stdlib/datetime/year.go b/pkg/stdlib/datetime/year.go index 69303fac..6251d58a 100644 --- a/pkg/stdlib/datetime/year.go +++ b/pkg/stdlib/datetime/year.go @@ -9,8 +9,8 @@ import ( ) // DATE_YEAR returns the year extracted from the given date. -// @params date (DateTime) - source DateTime. -// @return (Int) - a year number. +// @param {DateTime} date - Source DateTime. +// @return {Int} - A year number. func DateYear(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) if err != nil { diff --git a/pkg/stdlib/html/attr_get.go b/pkg/stdlib/html/attr_get.go index 39e9856b..cd74f578 100644 --- a/pkg/stdlib/html/attr_get.go +++ b/pkg/stdlib/html/attr_get.go @@ -9,9 +9,9 @@ import ( ) // ATTR_GET gets single or more attribute(s) of a given element. -// @param el (HTMLElement) - Target element. -// @param names (...String) - Attribute name(s). -// @returns Object - Key-value pairs of attribute values. +// @param {HTMLPage | HTMLDocument | HTMLElement} node - Target node. +// @param {String, repeated} attrNames - Attribute name(s). +// @return {Object} - Key-value pairs of attribute values. func AttributeGet(ctx context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 2, core.MaxArgs) diff --git a/pkg/stdlib/html/attr_remove.go b/pkg/stdlib/html/attr_remove.go index ad5110f0..5d96e9f8 100644 --- a/pkg/stdlib/html/attr_remove.go +++ b/pkg/stdlib/html/attr_remove.go @@ -10,8 +10,8 @@ import ( ) // ATTR_REMOVE removes single or more attribute(s) of a given element. -// @param el (HTMLElement) - Target element. -// @param names (...String) - Attribute name(s). +// @param {HTMLPage | HTMLDocument | HTMLElement} node - Target node. +// @param {String, repeated} attrNames - Attribute name(s). func AttributeRemove(ctx context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 2, core.MaxArgs) diff --git a/pkg/stdlib/html/attr_set.go b/pkg/stdlib/html/attr_set.go index 33fcc15d..7cfb868c 100644 --- a/pkg/stdlib/html/attr_set.go +++ b/pkg/stdlib/html/attr_set.go @@ -10,9 +10,9 @@ import ( ) // ATTR_SET sets or updates a single or more attribute(s) of a given element. -// @param el (HTMLElement) - Target element. -// @param nameOrObj (String | Object) - Attribute name or an object representing a key-value pair of attributes. -// @param value (String) - If a second parameter is a string value, this parameter represent an attribute value. +// @param {HTMLPage | HTMLDocument | HTMLElement} node - Target node. +// @param {String | Object} nameOrObj - Attribute name or an object representing a key-value pair of attributes. +// @param {String} value - If a second parameter is a string value, this parameter represent an attribute value. func AttributeSet(ctx context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 2, core.MaxArgs) diff --git a/pkg/stdlib/html/blur.go b/pkg/stdlib/html/blur.go index 8569bcf9..22c619b1 100644 --- a/pkg/stdlib/html/blur.go +++ b/pkg/stdlib/html/blur.go @@ -9,8 +9,8 @@ import ( ) // BLUR Calls blur on the element. -// @param target (HTMLPage | HTMLDocument | HTMLElement) - Target node. -// @param selector (String, optional) - Optional CSS selector. +// @param {HTMLPage | HTMLDocument | HTMLElement} node - Target node. +// @param {String} [selector] - CSS selector. func Blur(ctx context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 2) diff --git a/pkg/stdlib/html/clear.go b/pkg/stdlib/html/clear.go index 68834f1b..204d9f3e 100644 --- a/pkg/stdlib/html/clear.go +++ b/pkg/stdlib/html/clear.go @@ -9,8 +9,8 @@ import ( ) // INPUT_CLEAR clears a value from an underlying input element. -// @param source (HTMLPage | HTMLDocument | HTMLElement) - Event target. -// @param selector (String, options) - Selector. +// @param {HTMLPage | HTMLDocument | HTMLElement} node - Target html node. +// @param {String} [selector] - CSS selector. func InputClear(ctx context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 2) diff --git a/pkg/stdlib/html/click.go b/pkg/stdlib/html/click.go index 13570e4f..a0b2c63d 100644 --- a/pkg/stdlib/html/click.go +++ b/pkg/stdlib/html/click.go @@ -10,9 +10,9 @@ import ( ) // CLICK dispatches click event on a given element -// @param source (Open | GetElement) - Event source. -// @param selectorOrCount (String | Int, optional) - Optional selector or count of clicks. -// @param count (Int, optional) - Optional count of clicks. +// @param {HTMLPage | HTMLDocument | HTMLElement} node - Target html node. +// @param {String | Int} [cssSelectorOrClicks] - CSS selector or count of clicks. +// @param {Int} [clicks=1] - Count of clicks. func Click(ctx context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 3) diff --git a/pkg/stdlib/html/click_all.go b/pkg/stdlib/html/click_all.go index 186c39d6..2af5ea38 100644 --- a/pkg/stdlib/html/click_all.go +++ b/pkg/stdlib/html/click_all.go @@ -10,10 +10,10 @@ import ( ) // CLICK_ALL dispatches click event on all matched element -// @param source (Open) - Open. -// @param selector (String) - Selector. -// @param count (Int, optional) - Optional count of clicks. -// @returns (Boolean) - Returns true if matched at least one element. +// @param {HTMLPage | HTMLDocument | HTMLElement} node - Target html node. +// @param {String} selector - CSS selector. +// @param {Int} [clicks=1] - Optional count of clicks. +// @return {Boolean} - True if matched at least one element. func ClickAll(ctx context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 2, 3) diff --git a/pkg/stdlib/html/cookie_del.go b/pkg/stdlib/html/cookie_del.go index ab489ffa..e5225fec 100644 --- a/pkg/stdlib/html/cookie_del.go +++ b/pkg/stdlib/html/cookie_del.go @@ -10,8 +10,8 @@ import ( ) // COOKIE_DEL gets a cookie from a given page by name. -// @param page (HTMLPage) - Target page. -// @param cookie (...HTTPCookie|String) - Cookie or cookie name to delete. +// @param {HTMLPage} page - Target page. +// @param {HTTPCookie, repeated | String, repeated} cookiesOrNames - Cookie or cookie name to delete. func CookieDel(ctx context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 2, core.MaxArgs) diff --git a/pkg/stdlib/html/cookie_get.go b/pkg/stdlib/html/cookie_get.go index 60603011..e97d8d12 100644 --- a/pkg/stdlib/html/cookie_get.go +++ b/pkg/stdlib/html/cookie_get.go @@ -10,8 +10,9 @@ import ( ) // COOKIE_GET gets a cookie from a given page by name. -// @param page (HTMLPage) - Target page. -// @param name (String) - Cookie or cookie name to delete. +// @param {HTMLPage} page - Target page. +// @param {String} name - Cookie or cookie name to delete. +// @return {HTTPCookie} - Cookie if found, otherwise None. func CookieGet(ctx context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 2, 2) diff --git a/pkg/stdlib/html/cookie_set.go b/pkg/stdlib/html/cookie_set.go index 3c17c09c..f7ea34fd 100644 --- a/pkg/stdlib/html/cookie_set.go +++ b/pkg/stdlib/html/cookie_set.go @@ -9,8 +9,8 @@ import ( ) // COOKIE_SET sets cookies to a given page -// @param page (HTMLPage) - Target page. -// @param cookie... (HTTPCookie) - Target cookies. +// @param {HTMLPage} page - Target page. +// @param {HTTPCookie, repeated} cookies - Target cookies. func CookieSet(ctx context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 2, core.MaxArgs) diff --git a/pkg/stdlib/html/document.go b/pkg/stdlib/html/document.go index c2769ee7..bcec602b 100644 --- a/pkg/stdlib/html/document.go +++ b/pkg/stdlib/html/document.go @@ -20,16 +20,20 @@ type PageLoadParams struct { // DOCUMENT opens an HTML page by a given url. // By default, loads a page by http call - resulted page does not support any interactions. -// @param params (Object) - Optional, An object containing the following properties : -// driver (String) - Optional, driver name. -// timeout (Int) - Optional, timeout. -// userAgent (String) - Optional, user agent. -// keepCookies (Boolean) - Optional, boolean value indicating whether to use cookies from previous sessions. -// i.e. not to open a page in the Incognito mode. -// cookies (HTTPCookies) - Optional, set of HTTP cookies. -// headers (HTTPHeaders) - Optional, HTTP headers. -// viewport (Viewport) - Optional, viewport params. -// @returns (HTMLPage) - Returns loaded HTML page. +// @param {Object} [params] - An object containing the following properties : +// @param {String} [params.driver] - Driver name to use. +// @param {Int} [params.timeout=60000] - Page load timeout. +// @param {String} [params.userAgent] - Custom user agent. +// @param {Boolean} [params.keepCookies=False] - Boolean value indicating whether to use cookies from previous sessions i.e. not to open a page in the Incognito mode. +// @param {HTTPCookies} [params.cookies] - Set of HTTP cookies to use during page loading. +// @param {HTTPHeaders} [params.headers] - Set of HTTP headers to use during page loading. +// @param {Object} [params.viewport] - Viewport params. +// @param {Int} [params.viewport.height] - Viewport height. +// @param {Int} [params.viewport.width] - Viewport width. +// @param {Float} [params.viewport.scaleFactor] - Viewport scale factor. +// @param {Boolean} [params.viewport.mobile] - Value that indicates whether to emulate mobile device. +// @param {Boolean} [params.viewport.landscape] - Value that indicates whether to render a page in landscape position. +// @return {HTMLPage} - Loaded HTML page. func Open(ctx context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 2) diff --git a/pkg/stdlib/html/download.go b/pkg/stdlib/html/download.go index 146dcd8a..702488ab 100644 --- a/pkg/stdlib/html/download.go +++ b/pkg/stdlib/html/download.go @@ -11,8 +11,8 @@ import ( ) // DOWNLOAD downloads a resource from the given GetURL. -// @param GetURL (String) - GetURL to download. -// @returns data (Binary) - Returns a base64 encoded string in binary format. +// @param {String} url - URL to download. +// @return {Binary} - A base64 encoded string in binary format. func Download(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/html/element.go b/pkg/stdlib/html/element.go index d86d439b..644f7451 100644 --- a/pkg/stdlib/html/element.go +++ b/pkg/stdlib/html/element.go @@ -11,9 +11,9 @@ import ( // ELEMENT finds an element by a given CSS selector. // Returns NONE if element not found. -// @param docOrEl (HTMLDocument|HTMLElement) - Parent document or element. -// @param selector (String) - CSS selector. -// @returns (HTMLElement | None) - Returns an HTMLElement if found, otherwise NONE. +// @param {HTMLPage | HTMLDocument | HTMLElement} node - Target html node. +// @param {String} selector - CSS selector. +// @return {HTMLElement} - A matched HTML element func Element(ctx context.Context, args ...core.Value) (core.Value, error) { el, selector, err := queryArgs(args) diff --git a/pkg/stdlib/html/element_exists.go b/pkg/stdlib/html/element_exists.go index d5f8b3d9..e6aeee53 100644 --- a/pkg/stdlib/html/element_exists.go +++ b/pkg/stdlib/html/element_exists.go @@ -8,9 +8,9 @@ import ( ) // ELEMENT_EXISTS returns a boolean value indicating whether there is an element matched by selector. -// @param docOrEl (HTMLDocument|HTMLNode) - Parent document or element. -// @param selector (String) - CSS selector. -// @returns (Boolean) - A boolean value indicating whether there is an element matched by selector. +// @param {HTMLPage | HTMLDocument | HTMLElement} node - Target html node. +// @param {String} selector - CSS selector. +// @return {Boolean} - A boolean value indicating whether there is an element matched by selector. func ElementExists(ctx context.Context, args ...core.Value) (core.Value, error) { el, selector, err := queryArgs(args) diff --git a/pkg/stdlib/html/elements.go b/pkg/stdlib/html/elements.go index a0e5daac..a7d0a7b5 100644 --- a/pkg/stdlib/html/elements.go +++ b/pkg/stdlib/html/elements.go @@ -9,9 +9,9 @@ import ( // ELEMENTS finds HTML elements by a given CSS selector. // Returns an empty array if element not found. -// @param docOrEl (HTMLDocument|HTMLNode) - Parent document or element. -// @param selector (String) - CSS selector. -// @returns (Array) - Returns an array of found HTML element. +// @param {HTMLPage | HTMLDocument | HTMLElement} node - Target html node. +// @param {String} selector - CSS selector. +// @return {HTMLElement[]} - An array of matched HTML elements. func Elements(ctx context.Context, args ...core.Value) (core.Value, error) { el, selector, err := queryArgs(args) diff --git a/pkg/stdlib/html/elements_count.go b/pkg/stdlib/html/elements_count.go index 33fc21a4..7f3666af 100644 --- a/pkg/stdlib/html/elements_count.go +++ b/pkg/stdlib/html/elements_count.go @@ -9,9 +9,9 @@ import ( // ELEMENTS_COUNT returns a number of found HTML elements by a given CSS selector. // Returns an empty array if element not found. -// @param docOrEl (HTMLDocument|HTMLNode) - Parent document or element. -// @param selector (String) - CSS selector. -// @returns (Int) - A number of found HTML elements by a given CSS selector. +// @param {HTMLPage | HTMLDocument | HTMLElement} node - Target html node. +// @param {String} selector - CSS selector. +// @return {Int} - A number of matched HTML elements by a given CSS selector. func ElementsCount(ctx context.Context, args ...core.Value) (core.Value, error) { el, selector, err := queryArgs(args) diff --git a/pkg/stdlib/html/find_frames.go b/pkg/stdlib/html/find_frames.go index 1de372dc..d3d8d51f 100644 --- a/pkg/stdlib/html/find_frames.go +++ b/pkg/stdlib/html/find_frames.go @@ -9,10 +9,10 @@ import ( // FRAMES finds HTML frames by a given property selector. // Returns an empty array if frames not found. -// @param page (HTMLPage) - HTML page. -// @param prop (String) - Property selector. -// @param value (Any) - Property value. -// @returns (Array) - Returns an array of found HTML frames. +// @param {HTMLPage} page - HTML page. +// @param {String} property - Property selector. +// @param {Any} value - Property value. +// @return {HTMLDocument[]} - Returns an array of found HTML frames. func Frames(ctx context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 3, 3) diff --git a/pkg/stdlib/html/focus.go b/pkg/stdlib/html/focus.go index 1cdc8487..f96a6ba2 100644 --- a/pkg/stdlib/html/focus.go +++ b/pkg/stdlib/html/focus.go @@ -9,8 +9,8 @@ import ( ) // FOCUS Sets focus on the element. -// @param target (HTMLPage | HTMLDocument | HTMLElement) - Target node. -// @param selector (String, optional) - Optional CSS selector. +// @param {HTMLPage | HTMLDocument | HTMLElement} node - Target html node. +// @param {String} [selector] - CSS selector. func Focus(ctx context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 2) diff --git a/pkg/stdlib/html/get_inner_html.go b/pkg/stdlib/html/get_inner_html.go index 11f4c55d..7c036fea 100644 --- a/pkg/stdlib/html/get_inner_html.go +++ b/pkg/stdlib/html/get_inner_html.go @@ -10,9 +10,9 @@ import ( ) // INNER_HTML returns inner HTML string of a given or matched by CSS selector element -// @param doc (Open|GetElement) - Parent document or element. -// @param selector (String, optional) - String of CSS selector. -// @returns (String) - Inner HTML string if an element found, otherwise empty string. +// @param {HTMLPage | HTMLDocument | HTMLElement} node - Target html node. +// @param {String} [selector] - String of CSS selector. +// @return {String} - Inner HTML string if a matched element, otherwise empty string. func GetInnerHTML(ctx context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 2) diff --git a/pkg/stdlib/html/get_inner_html_all.go b/pkg/stdlib/html/get_inner_html_all.go index 4ae83cfa..62bd862f 100644 --- a/pkg/stdlib/html/get_inner_html_all.go +++ b/pkg/stdlib/html/get_inner_html_all.go @@ -10,9 +10,9 @@ import ( ) // INNER_HTML_ALL returns an array of inner HTML strings of matched elements. -// @param doc (HTMLDocument|HTMLElement) - Parent document or element. -// @param selector (String) - String of CSS selector. -// @returns (String) - An array of inner HTML strings if any element found, otherwise empty array. +// @param {HTMLPage | HTMLDocument | HTMLElement} node - Target html node. +// @param {String} selector - String of CSS selector. +// @return {String[]} - An array of inner HTML strings if all matched elements, otherwise empty array. func GetInnerHTMLAll(ctx context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 2, 2) diff --git a/pkg/stdlib/html/get_inner_text.go b/pkg/stdlib/html/get_inner_text.go index 424e2b6a..0c358f0c 100644 --- a/pkg/stdlib/html/get_inner_text.go +++ b/pkg/stdlib/html/get_inner_text.go @@ -10,9 +10,9 @@ import ( ) // INNER_TEXT returns inner text string of a given or matched by CSS selector element -// @param doc (HTMLDocument|HTMLElement) - Parent document or element. -// @param selector (String, optional) - String of CSS selector. -// @returns (String) - Inner text if an element found, otherwise empty string. +// @param {HTMLPage | HTMLDocument | HTMLElement} node - Target html node. +// @param {String} [selector] - String of CSS selector. +// @return {String} - Inner text if a matched element, otherwise empty string. func GetInnerText(ctx context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 2) diff --git a/pkg/stdlib/html/get_inner_text_all.go b/pkg/stdlib/html/get_inner_text_all.go index 169f94cb..050adefa 100644 --- a/pkg/stdlib/html/get_inner_text_all.go +++ b/pkg/stdlib/html/get_inner_text_all.go @@ -10,9 +10,9 @@ import ( ) // INNER_TEXT_ALL returns an array of inner text of matched elements. -// @param doc (HTMLDocument|HTMLElement) - Parent document or element. -// @param selector (String) - String of CSS selector. -// @returns (String) - An array of inner text if any element found, otherwise empty array. +// @param {HTMLPage | HTMLDocument | HTMLElement} node - Target html node. +// @param {String} selector - String of CSS selector. +// @return {String[]} - An array of inner text if all matched elements, otherwise empty array. func GetInnerTextAll(ctx context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 2, 2) diff --git a/pkg/stdlib/html/hover.go b/pkg/stdlib/html/hover.go index f198add6..c6e45a67 100644 --- a/pkg/stdlib/html/hover.go +++ b/pkg/stdlib/html/hover.go @@ -11,8 +11,8 @@ import ( // HOVER fetches an element with selector, scrolls it into view if needed, and then uses page.mouse to hover over the center of the element. // If there's no element matching selector, the method returns an error. -// @param docOrEl (HTMLDocument|HTMLElement) - Target document or element. -// @param selector (String, options) - If document is passed, this param must represent an element selector. +// @param {HTMLPage | HTMLDocument | HTMLElement} node - Target html node. +// @param {String} [selector] - If document is passed, this param must represent an element selector. func Hover(ctx context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 2) diff --git a/pkg/stdlib/html/input.go b/pkg/stdlib/html/input.go index 021b3b44..8d4a954d 100644 --- a/pkg/stdlib/html/input.go +++ b/pkg/stdlib/html/input.go @@ -9,11 +9,11 @@ import ( ) // INPUT types a value to an underlying input element. -// @param source (HTMLPage | HTMLDocument | HTMLElement) - Event target. -// @param valueOrSelector (String) - Selector or a value. -// @param value (String) - Target value. -// @param delay (Int, optional) - Target value. -// @returns (Boolean) - Returns true if an element was found. +// @param {HTMLPage | HTMLDocument | HTMLElement} node - Target html node. +// @param {String} valueOrSelector - CSS selector or a value. +// @param {String} value - Target value. +// @param {Int} [delay] - Target value. +// @return {Boolean} - Returns true if an element was found. func Input(ctx context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 2, 4) diff --git a/pkg/stdlib/html/mouse_xy.go b/pkg/stdlib/html/mouse_xy.go index 4c240ee1..e2c0606a 100644 --- a/pkg/stdlib/html/mouse_xy.go +++ b/pkg/stdlib/html/mouse_xy.go @@ -10,9 +10,9 @@ import ( ) // MOUSE moves mouse by given coordinates. -// @param doc (HTMLDocument) - HTML document. -// @param x (Int|Float) - X coordinate. -// @param y (Int|Float) - Y coordinate. +// @param {HTMLDocument} document - HTML document. +// @param {Int|Float} x - X coordinate. +// @param {Int|Float} y - Y coordinate. func MouseMoveXY(ctx context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 3, 3) diff --git a/pkg/stdlib/html/navigate.go b/pkg/stdlib/html/navigate.go index 8a7de4d0..7f1148ae 100644 --- a/pkg/stdlib/html/navigate.go +++ b/pkg/stdlib/html/navigate.go @@ -12,9 +12,9 @@ import ( // NAVIGATE navigates a given page to a new resource. // The operation blocks the execution until the page gets loaded. // Which means there is no need in WAIT_NAVIGATION function. -// @param page (HTMLPage) - Target page. -// @param url (String) - Target url to navigate. -// @param timeout (Int, optional) - Optional timeout. Default is 5000. +// @param {HTMLPage} page - Target page. +// @param {String} url - Target url to navigate. +// @param {Int} [timeout=5000] - Navigation timeout. func Navigate(ctx context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 2, 3) diff --git a/pkg/stdlib/html/navigate_back.go b/pkg/stdlib/html/navigate_back.go index 23ff3b89..5ffe8089 100644 --- a/pkg/stdlib/html/navigate_back.go +++ b/pkg/stdlib/html/navigate_back.go @@ -12,10 +12,10 @@ import ( // NAVIGATE_BACK navigates a given page back within its navigation history. // The operation blocks the execution until the page gets loaded. // If the history is empty, the function returns FALSE. -// @param page (HTMLPage) - Target page. -// @param entry (Int, optional) - Optional value indicating how many pages to skip. Default 1. -// @param timeout (Int, optional) - Optional timeout. Default is 5000. -// @returns (Boolean) - Returns TRUE if history exists and the operation succeeded, otherwise FALSE. +// @param {HTMLPage} page - Target page. +// @param {Int} [entry=1] - An integer value indicating how many pages to skip. +// @param {Int} [timeout=5000] - Navigation timeout. +// @return {Boolean} - True if history exists and the operation succeeded, otherwise false. func NavigateBack(ctx context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 3) diff --git a/pkg/stdlib/html/navigate_forward.go b/pkg/stdlib/html/navigate_forward.go index a6b853a3..eea4339a 100644 --- a/pkg/stdlib/html/navigate_forward.go +++ b/pkg/stdlib/html/navigate_forward.go @@ -12,10 +12,10 @@ import ( // NAVIGATE_FORWARD navigates a given page forward within its navigation history. // The operation blocks the execution until the page gets loaded. // If the history is empty, the function returns FALSE. -// @param page (HTMLPage) - Target page. -// @param entry (Int, optional) - Optional value indicating how many pages to skip. Default 1. -// @param timeout (Int, optional) - Optional timeout. Default is 5000. -// @returns (Boolean) - Returns TRUE if history exists and the operation succeeded, otherwise FALSE. +// @param {HTMLPage} page - Target page. +// @param {Int} [entry=1] - An integer value indicating how many pages to skip. +// @param {Int} [timeout=5000] - Navigation timeout. +// @return {Boolean} - True if history exists and the operation succeeded, otherwise false. func NavigateForward(ctx context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 3) diff --git a/pkg/stdlib/html/pagination.go b/pkg/stdlib/html/pagination.go index 198a0244..c8680565 100644 --- a/pkg/stdlib/html/pagination.go +++ b/pkg/stdlib/html/pagination.go @@ -12,8 +12,8 @@ import ( // PAGINATION creates an iterator that goes through pages using CSS selector. // The iterator starts from the current page i.e. it does not change the page on 1st iteration. // That allows you to keep scraping logic inside FOR loop. -// @param doc (Open) - Target document. -// @param selector (String) - CSS selector for a pagination on the page. +// @param {HTMLPage | HTMLDocument | HTMLElement} node - Target html node. +// @param {String} selector - CSS selector for a pagination on the page. func Pagination(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 2, 2) diff --git a/pkg/stdlib/html/parse.go b/pkg/stdlib/html/parse.go index 97e7451b..00e29118 100644 --- a/pkg/stdlib/html/parse.go +++ b/pkg/stdlib/html/parse.go @@ -16,14 +16,19 @@ type ParseParams struct { } // PARSE loads an HTML page from a given string or byte array -// @param params (Object) - Optional, an object containing the following properties : -// driver (String) - Optional, driver name. -// keepCookies (Boolean) - Optional, boolean value indicating whether to use cookies from previous sessions. -// i.e. not to open a page in the Incognito mode. -// cookies (HTTPCookies) - Optional, set of HTTP cookies. -// headers (HTTPHeaders) - Optional, HTTP headers. -// viewport (Viewport) - Optional, viewport params. -// @returns (HTMLPage) - Returns parsed and loaded HTML page. +// @param {String} html - HTML string to parse. +// @param {Object} [params] - An object containing the following properties: +// @param {String} [params.driver] - Name of a driver to parse with. +// @param {Boolean} [params.keepCookies=False] - Boolean value indicating whether to use cookies from previous sessions i.e. not to open a page in the Incognito mode. +// @param {HTTPCookies} [params.cookies] - Set of HTTP cookies to use during page loading. +// @param {HTTPHeaders} [params.headers] - Set of HTTP headers to use during page loading. +// @param {Object} [params.viewport] - Viewport params. +// @param {Int} [params.viewport.height] - Viewport height. +// @param {Int} [params.viewport.width] - Viewport width. +// @param {Float} [params.viewport.scaleFactor] - Viewport scale factor. +// @param {Boolean} [params.viewport.mobile] - Value that indicates whether to emulate mobile device. +// @param {Boolean} [params.viewport.landscape] - Value that indicates whether to render a page in landscape position. +// @return {HTMLPage} - Returns parsed and loaded HTML page. func Parse(ctx context.Context, args ...core.Value) (core.Value, error) { if err := core.ValidateArgs(args, 1, 2); err != nil { return values.None, err diff --git a/pkg/stdlib/html/pdf.go b/pkg/stdlib/html/pdf.go index d4827e84..da84661a 100644 --- a/pkg/stdlib/html/pdf.go +++ b/pkg/stdlib/html/pdf.go @@ -22,24 +22,24 @@ func ValidatePageRanges(pageRanges string) (bool, error) { } // PDF prints a PDF of the current page. -// @param target (HTMLPage|String) - Target page or url. -// @param params (Object) - Optional, An object containing the following properties : -// Landscape (Bool) - Paper orientation. Defaults to false. -// DisplayHeaderFooter (Bool) - Display header and footer. Defaults to false. -// PrintBackground (Bool) - Print background graphics. Defaults to false. -// Scale (Float64) - Scale of the webpage rendering. Defaults to 1. -// PaperWidth (Float64) - Paper width in inches. Defaults to 8.5 inches. -// PaperHeight (Float64) - Paper height in inches. Defaults to 11 inches. -// MarginTop (Float64) - Top margin in inches. Defaults to 1cm (~0.4 inches). -// MarginBottom (Float64) - Bottom margin in inches. Defaults to 1cm (~0.4 inches). -// MarginLeft (Float64) - Left margin in inches. Defaults to 1cm (~0.4 inches). -// MarginRight (Float64) - Right margin in inches. Defaults to 1cm (~0.4 inches). -// PageRanges (String) - Paper ranges to print, e.g., '1-5, 8, 11-13'. Defaults to the empty string, which means print all pages. -// IgnoreInvalidPageRanges (Bool) - to silently ignore invalid but successfully parsed page ranges, such as '3-2'. Defaults to false. -// HeaderTemplate (String) - HTML template for the print header. Should be valid HTML markup with following classes used to inject printing values into them: - `date`: formatted print date - `title`: document title - `url`: document location - `pageNumber`: current page number - `totalPages`: total pages in the document For example, `` would generate span containing the title. -// FooterTemplate (String) - HTML template for the print footer. Should use the same format as the `headerTemplate`. -// PreferCSSPageSize (Bool) - Whether or not to prefer page size as defined by css. Defaults to false, in which case the content will be scaled to fit the paper size. * -// @returns data (Binary) - Returns a base64 encoded string in binary format. +// @param {HTMLPage | String}target - Target page or url. +// @param {Object} [params] - An object containing the following properties: +// @param {Bool} [params.landscape=False] - Paper orientation. +// @param {Bool} [params.displayHeaderFooter=False] - Display header and footer. +// @param {Bool} [params.printBackground=False] - Print background graphics. +// @param {Float} [params.scale=1] - Scale of the webpage rendering. +// @param {Float} [params.paperWidth=22] - Paper width in inches. +// @param {Float} [params.paperHeight=28] - Paper height in inches. +// @param {Float} [params.marginTo=1] - Top margin in inches. +// @param {Float} [params.marginBottom=1] - Bottom margin in inches. +// @param {Float} [params.marginLeft=1] - Left margin in inches. +// @param {Float} [params.marginRight=1] - Right margin in inches. +// @param {String} [params.pageRanges] - Paper ranges to print, e.g., '1-5, 8, 11-13'. +// @param {Bool} [params.ignoreInvalidPageRanges=False] - to silently ignore invalid but successfully parsed page ranges, such as '3-2'. +// @param {String} [params.headerTemplate] - HTML template for the print header. Should be valid HTML markup with following classes used to inject printing values into them: - `date`: formatted print date - `title`: document title - `url`: document location - `pageNumber`: current page number - `totalPages`: total pages in the document For example, `` would generate span containing the title. +// @param {String} [params.footerTemplate] - HTML template for the print footer. Should use the same format as the `headerTemplate`. +// @param {Bool} [params.preferCSSPageSize=False] - Whether or not to prefer page size as defined by css. Defaults to false, in which case the content will be scaled to fit the paper size. * +// @return {Binary} - PDF document in binary format. func PDF(ctx context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 2) diff --git a/pkg/stdlib/html/screenshot.go b/pkg/stdlib/html/screenshot.go index 230e534d..45770c61 100644 --- a/pkg/stdlib/html/screenshot.go +++ b/pkg/stdlib/html/screenshot.go @@ -11,15 +11,15 @@ import ( ) // SCREENSHOT takes a screenshot of a given page. -// @param target (HTMLPage|String) - Target page or url. -// @param params (Object) - Optional, An object containing the following properties : -// x (Float|Int) - Optional, X position of the viewport. -// x (Float|Int) - Optional,Y position of the viewport. -// width (Float|Int) - Optional, Width of the viewport. -// height (Float|Int) - Optional, Height of the viewport. -// format (String) - Optional, Either "jpeg" or "png". -// quality (Int) - Optional, Quality, in [0, 100], only for jpeg format. -// @returns data (Binary) - Returns a base64 encoded string in binary format. +// @param {HTMLPage|String} target - Target page or url. +// @param {Object} [params] - An object containing the following properties : +// @param {Float | Int} [params.x=0] - X position of the viewport. +// @param {Float | Int} [params.y=0] - Y position of the viewport. +// @param {Float | Int} [params.width] - Width of the viewport. +// @param {Float | Int} [params.height] - Height of the viewport. +// @param {String} [params.format="jpeg"] - Either "jpeg" or "png". +// @param {Int} [params.quality=100] - Quality, in [0, 100], only for jpeg format. +// @return {Binary} - Screenshot in binary format. func Screenshot(ctx context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 2) diff --git a/pkg/stdlib/html/scroll_bottom.go b/pkg/stdlib/html/scroll_bottom.go index 26165f73..f2b946e5 100644 --- a/pkg/stdlib/html/scroll_bottom.go +++ b/pkg/stdlib/html/scroll_bottom.go @@ -9,8 +9,13 @@ import ( ) // SCROLL_BOTTOM scrolls the document's window to its bottom. -// @param doc (HTMLDocument) - Target document. -// @param options (ScrollOptions) - Scroll options. Optional. +// @param {HTMLDocument} document - HTML document. +// @param {Int | Float} x - X coordinate. +// @param {Int | Float} y - Y coordinate. +// @param {Object} [params] - Scroll params. +// @param {String} [params.behavior="instant"] - Scroll behavior +// @param {String} [params.block="center"] - Scroll vertical alignment. +// @param {String} [params.inline="center"] - Scroll horizontal alignment. func ScrollBottom(ctx context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 2) diff --git a/pkg/stdlib/html/scroll_element.go b/pkg/stdlib/html/scroll_element.go index 30dcdea0..b802bd76 100644 --- a/pkg/stdlib/html/scroll_element.go +++ b/pkg/stdlib/html/scroll_element.go @@ -12,9 +12,12 @@ import ( ) // SCROLL_ELEMENT scrolls an element on. -// @param docOrEl (HTMLDocument|HTMLElement) - Target document or element. -// @param selector (String) - If document is passed, this param must represent an element selector. -// @param options (ScrollOptions) - Scroll options. Optional. +// @param {HTMLPage | HTMLDocument | HTMLElement} node - Target html node. +// @param {String} selector - If document is passed, this param must represent an element selector. +// @param {Object} [params] - Scroll params. +// @param {String} [params.behavior="instant"] - Scroll behavior +// @param {String} [params.block="center"] - Scroll vertical alignment. +// @param {String} [params.inline="center"] - Scroll horizontal alignment. func ScrollInto(ctx context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 3) diff --git a/pkg/stdlib/html/scroll_top.go b/pkg/stdlib/html/scroll_top.go index 2ccea6ee..c3b79bb1 100644 --- a/pkg/stdlib/html/scroll_top.go +++ b/pkg/stdlib/html/scroll_top.go @@ -9,8 +9,13 @@ import ( ) // SCROLL_TOP scrolls the document's window to its top. -// @param doc (HTMLDocument) - Target document. -// @param options (ScrollOptions) - Scroll options. Optional. +// @param {HTMLDocument} document - HTML document. +// @param {Int | Float} x - X coordinate. +// @param {Int | Float} y - Y coordinate. +// @param {Object} [params] - Scroll params. +// @param {String} [params.behavior="instant"] - Scroll behavior +// @param {String} [params.block="center"] - Scroll vertical alignment. +// @param {String} [params.inline="center"] - Scroll horizontal alignment. func ScrollTop(ctx context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 2) diff --git a/pkg/stdlib/html/scroll_xy.go b/pkg/stdlib/html/scroll_xy.go index 638680e3..b1419168 100644 --- a/pkg/stdlib/html/scroll_xy.go +++ b/pkg/stdlib/html/scroll_xy.go @@ -10,10 +10,13 @@ import ( ) // SCROLL scrolls by given coordinates. -// @param doc (HTMLDocument) - HTML document. -// @param x (Int|Float) - X coordinate. -// @param y (Int|Float) - Y coordinate. -// @param options (ScrollOptions) - Scroll options. Optional. +// @param {HTMLDocument} document - HTML document. +// @param {Int | Float} x - X coordinate. +// @param {Int | Float} y - Y coordinate. +// @param {Object} [params] - Scroll params. +// @param {String} [params.behavior="instant"] - Scroll behavior +// @param {String} [params.block="center"] - Scroll vertical alignment. +// @param {String} [params.inline="center"] - Scroll horizontal alignment. func ScrollXY(ctx context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 3, 4) diff --git a/pkg/stdlib/html/select.go b/pkg/stdlib/html/select.go index f1238b40..7eb170cd 100644 --- a/pkg/stdlib/html/select.go +++ b/pkg/stdlib/html/select.go @@ -9,10 +9,10 @@ import ( ) // SELECT selects a value from an underlying select element. -// @param source (Open | GetElement) - Event target. -// @param valueOrSelector (String | Array) - Selector or a an array of strings as a value. -// @param value (Array) - Returns an array of selected values. +// @param {HTMLElement} element - Target html element. +// @param {String | String[]} valueOrSelector - Selector or a an array of strings as a value. +// @param {String[]} value - Target value. Optional. +// @return {String[]} - Array of selected values. func Select(ctx context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 2, 4) diff --git a/pkg/stdlib/html/set_inner_html.go b/pkg/stdlib/html/set_inner_html.go index c59735c4..cda731e1 100644 --- a/pkg/stdlib/html/set_inner_html.go +++ b/pkg/stdlib/html/set_inner_html.go @@ -10,9 +10,9 @@ import ( ) // INNER_HTML_SET sets inner HTML string to a given or matched by CSS selector element -// @param doc (Open|GetElement) - Parent document or element. -// @param selector (String, optional) - String of CSS selector. -// @param innerHTML (String) - String of inner HTML. +// @param {HTMLPage | HTMLDocument | HTMLElement} node - Target html node. +// @param {String} htmlOrSelector - HTML or CSS selector. +// @param {String} [html] - String of inner HTML. func SetInnerHTML(ctx context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 2, 3) diff --git a/pkg/stdlib/html/set_inner_text.go b/pkg/stdlib/html/set_inner_text.go index df1b0209..337bf96b 100644 --- a/pkg/stdlib/html/set_inner_text.go +++ b/pkg/stdlib/html/set_inner_text.go @@ -10,9 +10,9 @@ import ( ) // INNER_TEXT_SET sets inner text string to a given or matched by CSS selector element -// @param doc (Open|GetElement) - Parent document or element. -// @param selector (String, optional) - String of CSS selector. -// @param innerText (String) - String of inner text. +// @param {HTMLPage | HTMLDocument | HTMLElement} node - Target html node. +// @param {String} textOrCssSelector - String of CSS selector. +// @param {String} [text] - String of inner text. func SetInnerText(ctx context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 2, 3) diff --git a/pkg/stdlib/html/style_get.go b/pkg/stdlib/html/style_get.go index 9e2262fd..b2fca01f 100644 --- a/pkg/stdlib/html/style_get.go +++ b/pkg/stdlib/html/style_get.go @@ -9,9 +9,9 @@ import ( ) // STYLE_GET gets single or more style attribute value(s) of a given element. -// @param el (HTMLElement) - Target element. -// @param names (...String) - Style name(s). -// @returns Object - Key-value pairs of style values. +// @param {HTMLElement} element - Target html element. +// @param {String, repeated} names - Style name(s). +// @return {Object} - Collection of key-value pairs of style values. func StyleGet(ctx context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 2, core.MaxArgs) diff --git a/pkg/stdlib/html/style_remove.go b/pkg/stdlib/html/style_remove.go index 51bcfebb..15ecc57c 100644 --- a/pkg/stdlib/html/style_remove.go +++ b/pkg/stdlib/html/style_remove.go @@ -10,8 +10,8 @@ import ( ) // STYLE_REMOVE removes single or more style attribute value(s) of a given element. -// @param el (HTMLElement) - Target element. -// @param names (...String) - Style name(s). +// @param {HTMLElement} element - Target html element. +// @param {String, repeated} names - Style name(s). func StyleRemove(ctx context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 2, core.MaxArgs) diff --git a/pkg/stdlib/html/style_set.go b/pkg/stdlib/html/style_set.go index bad731c9..9c677672 100644 --- a/pkg/stdlib/html/style_set.go +++ b/pkg/stdlib/html/style_set.go @@ -10,9 +10,9 @@ import ( ) // STYLE_SET sets or updates a single or more style attribute value of a given element. -// @param el (HTMLElement) - Target element. -// @param nameOrObj (String | Object) - Style name or an object representing a key-value pair of attributes. -// @param value (String) - If a second parameter is a string value, this parameter represent a style value. +// @param {HTMLElement} element - Target html element. +// @param {String | Object} nameOrObj - Style name or an object representing a key-value pair of attributes. +// @param {String} value - If a second parameter is a string value, this parameter represent a style value. func StyleSet(ctx context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 2, core.MaxArgs) diff --git a/pkg/stdlib/html/wait_attr.go b/pkg/stdlib/html/wait_attr.go index 79f3a435..57c8364d 100644 --- a/pkg/stdlib/html/wait_attr.go +++ b/pkg/stdlib/html/wait_attr.go @@ -10,21 +10,21 @@ import ( ) // WAIT_ATTR waits until a target attribute's value appears -// @param node (HTMLPage | HTMLDocument | HTMLElement) - Parent document. -// @param attrNameOrSelector (String) - String of an attr name or CSS selector. -// @param attrValueOrAttrName (String | Any) - Attr value or name. -// @param attrValueOrTimeout (Any | Int, optional) - Attr value or an optional timeout. -// @param timeout (Int, optional) - Optional timeout. +// @param {HTMLPage | HTMLDocument | HTMLElement} node - Target html node. +// @param {String} attrNameOrSelector - String of an attr name or CSS selector. +// @param {String | Any} attrValueOrAttrName - Attr value or name. +// @param {Any | Int} [attrValueOrTimeout] - Attr value or a timeout. +// @param {Int} [timeout=5000] - Wait timeout. func WaitAttribute(ctx context.Context, args ...core.Value) (core.Value, error) { return waitAttributeWhen(ctx, args, drivers.WaitEventPresence) } // WAIT_NO_ATTR waits until a target attribute's value disappears -// @param node (HTMLPage | HTMLDocument | HTMLElement) - Parent document. -// @param attrNameOrSelector (String) - String of an attr name or CSS selector. -// @param attrValueOrAttrName (String | Any) - Attr value or name. -// @param attrValueOrTimeout (Any | Int, optional) - Attr value or an optional timeout. -// @param timeout (Int, optional) - Optional timeout. +// @param {HTMLPage | HTMLDocument | HTMLElement} node - Target html node. +// @param {String} attrNameOrSelector - String of an attr name or CSS selector. +// @param {String | Any} attrValueOrAttrName - Attr value or name. +// @param {Any | Int} [attrValueOrTimeout] - Attr value or wait timeout. +// @param {Int} [timeout=5000] - Wait timeout. func WaitNoAttribute(ctx context.Context, args ...core.Value) (core.Value, error) { return waitAttributeWhen(ctx, args, drivers.WaitEventAbsence) } diff --git a/pkg/stdlib/html/wait_attr_all.go b/pkg/stdlib/html/wait_attr_all.go index 82c05e4f..bf3d4d1f 100644 --- a/pkg/stdlib/html/wait_attr_all.go +++ b/pkg/stdlib/html/wait_attr_all.go @@ -11,20 +11,20 @@ import ( // WAIT_ATTR_ALL waits for an attribute to appear on all matched elements with a given value. // Stops the execution until the navigation ends or operation times out. -// @param doc (HTMLDocument) - Parent document. -// @param selector (String) - String of CSS selector. -// @param class (String) - String of target CSS class. -// @param timeout (Int, optional) - Optional timeout. +// @param {HTMLPage | HTMLDocument | HTMLElement} node - Target html node. +// @param {String} selector - String of CSS selector. +// @param {String} class - String of target CSS class. +// @param {Int} [timeout=5000] - Wait timeout. func WaitAttributeAll(ctx context.Context, args ...core.Value) (core.Value, error) { return waitAttributeAllWhen(ctx, args, drivers.WaitEventPresence) } // WAIT_NO_ATTR_ALL waits for an attribute to disappear on all matched elements by a given value. // Stops the execution until the navigation ends or operation times out. -// @param doc (HTMLDocument) - Parent document. -// @param selector (String) - String of CSS selector. -// @param class (String) - String of target CSS class. -// @param timeout (Int, optional) - Optional timeout. +// @param {HTMLPage | HTMLDocument | HTMLElement} node - Target html node. +// @param {String} selector - String of CSS selector. +// @param {String} class - String of target CSS class. +// @param {Int} [timeout=5000] - Wait timeout. func WaitNoAttributeAll(ctx context.Context, args ...core.Value) (core.Value, error) { return waitAttributeAllWhen(ctx, args, drivers.WaitEventAbsence) } diff --git a/pkg/stdlib/html/wait_class.go b/pkg/stdlib/html/wait_class.go index 76cc3de7..39d75ee1 100644 --- a/pkg/stdlib/html/wait_class.go +++ b/pkg/stdlib/html/wait_class.go @@ -11,26 +11,20 @@ import ( // WAIT_CLASS waits for a class to appear on a given element. // Stops the execution until the navigation ends or operation times out. -// @param node (HTMLPage | HTMLDocument | HTMLElement) - Target node. -// @param selectorOrClass (String) - If document is passed, this param must represent an element selector. -// Otherwise target class. -// @param classOrTimeout (String|Int, optional) - If document is passed, this param must represent target class name. -// Otherwise timeout. -// @param timeout (Int, optional) - If document is passed, this param must represent timeout. -// Otherwise not passed. +// @param {HTMLPage | HTMLDocument | HTMLElement} node - Target html node. +// @param {String} selectorOrClass - If document is passed, this param must represent an element selector. Otherwise target class. +// @param {String | Int} [classOrTimeout] - If document is passed, this param must represent target class name. Otherwise timeout. +// @param {Int} [timeout] - If document is passed, this param must represent timeout. Otherwise not passed. func WaitClass(ctx context.Context, args ...core.Value) (core.Value, error) { return waitClassWhen(ctx, args, drivers.WaitEventPresence) } // WAIT_NO_CLASS waits for a class to disappear on a given element. // Stops the execution until the navigation ends or operation times out. -// @param node (HTMLPage | HTMLDocument | HTMLElement) - Target node. -// @param selectorOrClass (String) - If document is passed, this param must represent an element selector. -// Otherwise target class. -// @param classOrTimeout (String|Int, optional) - If document is passed, this param must represent target class name. -// Otherwise timeout. -// @param timeout (Int, optional) - If document is passed, this param must represent timeout. -// Otherwise not passed. +// @param {HTMLPage | HTMLDocument | HTMLElement} node - Target html node. +// @param {String} selectorOrClass - If document is passed, this param must represent an element selector. Otherwise target class. +// @param {String | Int} [classOrTimeout] - If document is passed, this param must represent target class name. Otherwise timeout. +// @param {Int} [timeout] - If document is passed, this param must represent timeout. Otherwise not passed. func WaitNoClass(ctx context.Context, args ...core.Value) (core.Value, error) { return waitClassWhen(ctx, args, drivers.WaitEventAbsence) } diff --git a/pkg/stdlib/html/wait_class_all.go b/pkg/stdlib/html/wait_class_all.go index 2c4cee8f..b98deeb8 100644 --- a/pkg/stdlib/html/wait_class_all.go +++ b/pkg/stdlib/html/wait_class_all.go @@ -11,20 +11,20 @@ import ( // WAIT_CLASS_ALL waits for a class to appear on all matched elements. // Stops the execution until the navigation ends or operation times out. -// @param doc (HTMLDocument) - Parent document. -// @param selector (String) - String of CSS selector. -// @param class (String) - String of target CSS class. -// @param timeout (Int, optional) - Optional timeout. +// @param {HTMLPage | HTMLDocument | HTMLElement} node - Target html node. +// @param {String} selector - String of CSS selector. +// @param {String} class - String of target CSS class. +// @param {Int} [timeout=5000] - Wait timeout. func WaitClassAll(ctx context.Context, args ...core.Value) (core.Value, error) { return waitClassAllWhen(ctx, args, drivers.WaitEventPresence) } // WAIT_NO_CLASS_ALL waits for a class to disappear on all matched elements. // Stops the execution until the navigation ends or operation times out. -// @param doc (HTMLDocument) - Parent document. -// @param selector (String) - String of CSS selector. -// @param class (String) - String of target CSS class. -// @param timeout (Int, optional) - Optional timeout. +// @param {HTMLPage | HTMLDocument | HTMLElement} node - Target html node. +// @param {String} selector - String of CSS selector. +// @param {String} class - String of target CSS class. +// @param {Int} [timeout=5000] - Wait timeout. func WaitNoClassAll(ctx context.Context, args ...core.Value) (core.Value, error) { return waitClassAllWhen(ctx, args, drivers.WaitEventAbsence) } diff --git a/pkg/stdlib/html/wait_element.go b/pkg/stdlib/html/wait_element.go index 18fcd4ee..736e1f58 100644 --- a/pkg/stdlib/html/wait_element.go +++ b/pkg/stdlib/html/wait_element.go @@ -11,18 +11,18 @@ import ( // WAIT_ELEMENT waits for element to appear in the DOM. // Stops the execution until it finds an element or operation times out. -// @param n (HTMLDocument) - Driver HTMLDocument. -// @param selector (String) - Target element's selector. -// @param timeout (Int, optional) - Optional timeout. Default 5000 ms. +// @param {HTMLPage | HTMLDocument | HTMLElement} node - Target html node. +// @param {String} selector - Target element's selector. +// @param {Int} [timeout=5000] - Wait timeout. func WaitElement(ctx context.Context, args ...core.Value) (core.Value, error) { return waitElementWhen(ctx, args, drivers.WaitEventPresence) } // WAIT_NO_ELEMENT waits for element to disappear in the DOM. // Stops the execution until it does not find an element or operation times out. -// @param doc (HTMLDocument) - Driver HTMLDocument. -// @param selector (String) - Target element's selector. -// @param timeout (Int, optional) - Optional timeout. Default 5000 ms. +// @param {HTMLPage | HTMLDocument | HTMLElement} node - Target html node. +// @param {String} selector - Target element's selector. +// @param {Int} [timeout=5000] - Wait timeout. func WaitNoElement(ctx context.Context, args ...core.Value) (core.Value, error) { return waitElementWhen(ctx, args, drivers.WaitEventAbsence) } diff --git a/pkg/stdlib/html/wait_navigation.go b/pkg/stdlib/html/wait_navigation.go index 3ecabf9a..e4d18bca 100644 --- a/pkg/stdlib/html/wait_navigation.go +++ b/pkg/stdlib/html/wait_navigation.go @@ -18,8 +18,8 @@ type WaitNavigationParams struct { // WAIT_NAVIGATION waits for a given page to navigate to a new url. // Stops the execution until the navigation ends or operation times out. -// @param page (HTMLPage) - Target page. -// @param timeout (Int, optional) - Optional timeout. Default 5000 ms. +// @param {HTMLPage} page - Target page. +// @param {Int} [timeout=5000] - Navigation timeout. func WaitNavigation(ctx context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 2) diff --git a/pkg/stdlib/html/wait_style.go b/pkg/stdlib/html/wait_style.go index cf9d4d56..2accea3f 100644 --- a/pkg/stdlib/html/wait_style.go +++ b/pkg/stdlib/html/wait_style.go @@ -9,12 +9,22 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// WAIT_STYLE +// WAIT_STYLE waits until a target style value appears +// @param {HTMLPage | HTMLDocument | HTMLElement} node - Target html node. +// @param {String} styleNameOrSelector - Style name or CSS selector. +// @param {String | Any} valueOrStyleName - Style value or name. +// @param {Any | Int} [valueOrTimeout] - Style value or wait timeout. +// @param {Int} [timeout=5000] - Wait timeout. func WaitStyle(ctx context.Context, args ...core.Value) (core.Value, error) { return waitStyleWhen(ctx, args, drivers.WaitEventPresence) } -// WAIT_NO_STYLE +// WAIT_NO_STYLE waits until a target style value disappears +// @param {HTMLPage | HTMLDocument | HTMLElement} node - Target html node. +// @param {String} styleNameOrSelector - Style name or CSS selector. +// @param {String | Any} valueOrStyleName - Style value or name. +// @param {Any | Int} [valueOrTimeout] - Style value or wait timeout. +// @param {Int} [timeout=5000] - Wait timeout. func WaitNoStyle(ctx context.Context, args ...core.Value) (core.Value, error) { return waitStyleWhen(ctx, args, drivers.WaitEventAbsence) } diff --git a/pkg/stdlib/html/wait_style_all.go b/pkg/stdlib/html/wait_style_all.go index 1ce622be..ad84bad5 100644 --- a/pkg/stdlib/html/wait_style_all.go +++ b/pkg/stdlib/html/wait_style_all.go @@ -9,12 +9,22 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// WAIT_STYLE_ALL +// WAIT_STYLE_ALL waits until a target style value appears on all matched elements with a given value. +// @param {HTMLPage | HTMLDocument | HTMLElement} node - Target html node. +// @param {String} styleNameOrSelector - Style name or CSS selector. +// @param {String | Any} valueOrStyleName - Style value or name. +// @param {Any | Int} [valueOrTimeout] - Style value or wait timeout. +// @param {Int} [timeout=5000] - Timeout. func WaitStyleAll(ctx context.Context, args ...core.Value) (core.Value, error) { return waitStyleAllWhen(ctx, args, drivers.WaitEventPresence) } -// WAIT_NO_STYLE_ALL +// WAIT_NO_STYLE_ALL waits until a target style value disappears on all matched elements with a given value. +// @param {HTMLPage | HTMLDocument | HTMLElement} node - Target html node. +// @param {String} styleNameOrSelector - Style name or CSS selector. +// @param {String | Any} valueOrStyleName - Style value or name. +// @param {Any | Int} [valueOrTimeout] - Style value or wait timeout. +// @param {Int} [timeout=5000] - Timeout. func WaitNoStyleAll(ctx context.Context, args ...core.Value) (core.Value, error) { return waitStyleAllWhen(ctx, args, drivers.WaitEventAbsence) } diff --git a/pkg/stdlib/html/xpath.go b/pkg/stdlib/html/xpath.go index 0a31a732..086a97bc 100644 --- a/pkg/stdlib/html/xpath.go +++ b/pkg/stdlib/html/xpath.go @@ -9,9 +9,9 @@ import ( ) // XPATH evaluates the XPath expression. -// @param source (HTMLPage | HTMLDocument | HTMLElement) - Target HTML object. -// @param expression (String) - XPath expression. -// @returns (Value) - Returns result of a given XPath expression. +// @param {HTMLPage | HTMLDocument | HTMLElement} node - Target html node. +// @param {String} expression - XPath expression. +// @return {Any} - Returns result of a given XPath expression. func XPath(ctx context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 2, 2) diff --git a/pkg/stdlib/io/fs/lib.go b/pkg/stdlib/io/fs/lib.go index 6098823f..4c8b4332 100644 --- a/pkg/stdlib/io/fs/lib.go +++ b/pkg/stdlib/io/fs/lib.go @@ -5,6 +5,7 @@ import ( ) // RegisterLib register `FS` namespace functions. +// @namespace FS func RegisterLib(ns core.Namespace) error { return ns. Namespace("FS"). diff --git a/pkg/stdlib/io/fs/read.go b/pkg/stdlib/io/fs/read.go index 09e4a61f..cfc2394e 100644 --- a/pkg/stdlib/io/fs/read.go +++ b/pkg/stdlib/io/fs/read.go @@ -9,9 +9,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// Read reads from a given file. -// @params path (String) - path to file to read from. -// @returns data (Binary) - the read file in binary format. +// READ reads from a given file. +// @param {String} path - Path to file to read from. +// @return {Binary} - File content in binary format. func Read(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/io/fs/write.go b/pkg/stdlib/io/fs/write.go index f5da9cc6..eb48ad53 100644 --- a/pkg/stdlib/io/fs/write.go +++ b/pkg/stdlib/io/fs/write.go @@ -10,16 +10,14 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// Write writes the given data into the file. -// @params path (String) - path to file to write into. -// @params data (Binary) - data to write. -// @params params (Object) optional - additional parameters: -// * mode (String): -// * x - Exclusive: returns an error if the file exist. It can be -// combined with other modes -// * a - Append: will create a file if the specified file does not exist -// * w - Write (Default): will create a file if the specified file does not exist -// @returns None +// WRITE writes the given data into the file. +// @param {String} path - File path to write into. +// @param {Binary} data - Data to write. +// @param {Object} [params] - additional parameters: +// @param {String} [params.mode] - Write mode. +// * x - Exclusive: returns an error if the file exist. It can be combined with other modes +// * a - Append: will create a file if the specified file does not exist +// * w - Write (Default): will create a file if the specified file does not exist func Write(_ context.Context, args ...core.Value) (core.Value, error) { err := validateRequiredWriteArgs(args) if err != nil { diff --git a/pkg/stdlib/io/lib.go b/pkg/stdlib/io/lib.go index 9aff6c3b..25cf6447 100644 --- a/pkg/stdlib/io/lib.go +++ b/pkg/stdlib/io/lib.go @@ -7,6 +7,7 @@ import ( ) // RegisterLib register `IO` namespace functions. +// @namespace IO func RegisterLib(ns core.Namespace) error { io := ns.Namespace("IO") diff --git a/pkg/stdlib/io/net/http/delete.go b/pkg/stdlib/io/net/http/delete.go index 5440395c..aa238293 100644 --- a/pkg/stdlib/io/net/http/delete.go +++ b/pkg/stdlib/io/net/http/delete.go @@ -8,10 +8,11 @@ import ( ) // DELETE makes a HTTP DELETE request. -// @params params (Object) - request parameters. -// * url (String) - Target url -// * body (Binary) - POST data -// * headers (Object) optional - HTTP headers +// @param {Object} params - Request parameters. +// @param {String} params.url - Target url +// @param {Binary} params.body - Request data +// @param {Object} [params.headers] - HTTP headers +// @return {Binary} - Response in binary format func DELETE(ctx context.Context, args ...core.Value) (core.Value, error) { return execMethod(ctx, h.MethodDelete, args) } diff --git a/pkg/stdlib/io/net/http/get.go b/pkg/stdlib/io/net/http/get.go index d6b3a550..cf0ef57a 100644 --- a/pkg/stdlib/io/net/http/get.go +++ b/pkg/stdlib/io/net/http/get.go @@ -10,9 +10,10 @@ import ( ) // GET makes a HTTP GET request. -// @params url or (String) - target url or parameters. -// * url (String) - Target url -// * headers (Object) optional - HTTP headers +// @param {Object | String} urlOrParam - Target url or parameters. +// @param {String} [param.url] - Target url or parameters. +// @param {Object} [param.headers] - HTTP headers +// @return {Binary} - Response in binary format func GET(ctx context.Context, args ...core.Value) (core.Value, error) { if err := core.ValidateArgs(args, 1, 1); err != nil { return values.None, err diff --git a/pkg/stdlib/io/net/http/lib.go b/pkg/stdlib/io/net/http/lib.go index 68008e55..6fee8758 100644 --- a/pkg/stdlib/io/net/http/lib.go +++ b/pkg/stdlib/io/net/http/lib.go @@ -3,6 +3,7 @@ package http import "github.com/MontFerret/ferret/pkg/runtime/core" // RegisterLib register `HTTP` namespace functions. +// @namespace HTTP func RegisterLib(ns core.Namespace) error { return ns. Namespace("HTTP"). diff --git a/pkg/stdlib/io/net/http/post.go b/pkg/stdlib/io/net/http/post.go index a4f906ab..9b4f0a6b 100644 --- a/pkg/stdlib/io/net/http/post.go +++ b/pkg/stdlib/io/net/http/post.go @@ -8,10 +8,11 @@ import ( ) // POST makes a POST request. -// @params params (Object) - request parameters. -// * url (String) - Target url -// * body (Binary) - POST data -// * headers (Object) optional - HTTP headers +// @param {Object} params - Request parameters. +// @param {String} params.url - Target url +// @param {Binary} params.body - Request data +// @param {Object} [params.headers] - HTTP headers +// @return {Binary} - Response in binary format func POST(ctx context.Context, args ...core.Value) (core.Value, error) { return execMethod(ctx, h.MethodPost, args) } diff --git a/pkg/stdlib/io/net/http/put.go b/pkg/stdlib/io/net/http/put.go index 09cf565c..224cd567 100644 --- a/pkg/stdlib/io/net/http/put.go +++ b/pkg/stdlib/io/net/http/put.go @@ -8,10 +8,11 @@ import ( ) // PUT makes a PUT HTTP request. -// @params params (Object) - request parameters. -// * url (String) - Target url. -// * body (Binary) - POST data. -// * headers (Object) optional - HTTP headers. +// @param {Object} params - Request parameters. +// @param {String} params.url - Target url +// @param {Binary} params.body - Request data +// @param {Object} [params.headers] - HTTP headers +// @return {Binary} - Response in binary format func PUT(ctx context.Context, args ...core.Value) (core.Value, error) { return execMethod(ctx, h.MethodPut, args) } diff --git a/pkg/stdlib/io/net/http/request.go b/pkg/stdlib/io/net/http/request.go index ad0b0ff9..7abd0026 100644 --- a/pkg/stdlib/io/net/http/request.go +++ b/pkg/stdlib/io/net/http/request.go @@ -19,11 +19,12 @@ type Params struct { } // REQUEST makes a HTTP request. -// @params params (Object) - request parameters. -// * method (String) - HTTP method. -// * url (String) - Target url. -// * body (Binary) - POST data. -// * headers (Object) optional - HTTP headers. +// @param {Object} params - Request parameters. +// @param {String} params.method - HTTP method +// @param {String} params.url - Target url +// @param {Binary} params.body - Request data +// @param {Object} [params.headers] - HTTP headers +// @return {Binary} - Response in binary format func REQUEST(ctx context.Context, args ...core.Value) (core.Value, error) { return execMethod(ctx, "", args) } diff --git a/pkg/stdlib/io/net/lib.go b/pkg/stdlib/io/net/lib.go index f1a28f13..192388a6 100644 --- a/pkg/stdlib/io/net/lib.go +++ b/pkg/stdlib/io/net/lib.go @@ -6,6 +6,7 @@ import ( ) // RegisterLib register `NET` namespace functions. +// @namespace NET func RegisterLib(ns core.Namespace) error { io := ns.Namespace("NET") diff --git a/pkg/stdlib/math/abs.go b/pkg/stdlib/math/abs.go index f886e327..830d50d9 100644 --- a/pkg/stdlib/math/abs.go +++ b/pkg/stdlib/math/abs.go @@ -9,9 +9,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// Abs returns the absolute value of a given number. -// @param number (Int|Float) - Input number. -// @returns (Float) - The absolute value of a given number. +// ABS returns the absolute value of a given number. +// @param {Int | Float} number - Input number. +// @return {Float} - The absolute value of a given number. func Abs(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/math/acos.go b/pkg/stdlib/math/acos.go index e0884391..bd8a11cc 100644 --- a/pkg/stdlib/math/acos.go +++ b/pkg/stdlib/math/acos.go @@ -9,9 +9,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// Acos returns the arccosine, in radians, of a given number. -// @param number (Int|Float) - Input number. -// @returns (Float) - The arccosine, in radians, of a given number. +// ACOS returns the arccosine, in radians, of a given number. +// @param {Int | Float} number - Input number. +// @return {Float} - The arccosine, in radians, of a given number. func Acos(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/math/asin.go b/pkg/stdlib/math/asin.go index a98153de..c6693359 100644 --- a/pkg/stdlib/math/asin.go +++ b/pkg/stdlib/math/asin.go @@ -9,9 +9,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// Asin returns the arcsine, in radians, of a given number. -// @param number (Int|Float) - Input number. -// @returns (Float) - The arcsine, in radians, of a given number. +// ASIN returns the arcsine, in radians, of a given number. +// @param {Int | Float} number - Input number. +// @return {Float} - The arcsine, in radians, of a given number. func Asin(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/math/atan.go b/pkg/stdlib/math/atan.go index edf222c5..6de7630c 100644 --- a/pkg/stdlib/math/atan.go +++ b/pkg/stdlib/math/atan.go @@ -9,9 +9,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// Atan returns the arctangent, in radians, of a given number. -// @param number (Int|Float) - Input number. -// @returns (Float) - The arctangent, in radians, of a given number. +// ATAN returns the arctangent, in radians, of a given number. +// @param {Int | Float} number - Input number. +// @return {Float} - The arctangent, in radians, of a given number. func Atan(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/math/atan2.go b/pkg/stdlib/math/atan2.go index 348a9a46..a9a8112d 100644 --- a/pkg/stdlib/math/atan2.go +++ b/pkg/stdlib/math/atan2.go @@ -9,10 +9,10 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// Atan2 returns the arc tangent of y/x, using the signs of the two to determine the quadrant of the return value. -// @param number1 (Int|Float) - Input number. -// @param number2 (Int|Float) - Input number. -// @returns (Float) - The arc tangent of y/x, using the signs of the two to determine the quadrant of the return value. +// ATAN2 returns the arc tangent of y/x, using the signs of the two to determine the quadrant of the return value. +// @param {Int | Float} number1 - Input number. +// @param {Int | Float} number2 - Input number. +// @return {Float} - The arc tangent of y/x, using the signs of the two to determine the quadrant of the return value. func Atan2(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 2, 2) diff --git a/pkg/stdlib/math/average.go b/pkg/stdlib/math/average.go index e34a9cc9..ed0a24e4 100644 --- a/pkg/stdlib/math/average.go +++ b/pkg/stdlib/math/average.go @@ -8,9 +8,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// Average Returns the average (arithmetic mean) of the values in array. -// @param array (Array) - Array of numbers. -// @returns (Float) - The average of the values in array. +// AVERAGE Returns the average (arithmetic mean) of the values in array. +// @param {Int[] | Float[]} array - Array of numbers. +// @return {Float} - The average of the values in array. func Average(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/math/ceil.go b/pkg/stdlib/math/ceil.go index 0370cece..882ca892 100644 --- a/pkg/stdlib/math/ceil.go +++ b/pkg/stdlib/math/ceil.go @@ -9,9 +9,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// Ceil returns the least integer value greater than or equal to a given value. -// @param number (Int|Float) - Input number. -// @returns (Int) - The least integer value greater than or equal to a given value. +// CEIL returns the least integer value greater than or equal to a given value. +// @param {Int | Float} number - Input number. +// @return {Int} - The least integer value greater than or equal to a given value. func Ceil(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/math/cos.go b/pkg/stdlib/math/cos.go index e8471464..647b5dab 100644 --- a/pkg/stdlib/math/cos.go +++ b/pkg/stdlib/math/cos.go @@ -9,9 +9,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// Cos returns the cosine of a given number. -// @param number (Int|Float) - Input number. -// @returns (Float) - The cosine of a given number. +// COS returns the cosine of a given number. +// @param {Int | Float} number - Input number. +// @return {Float} - The cosine of a given number. func Cos(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/math/degrees.go b/pkg/stdlib/math/degrees.go index 330aa90b..c9f3856b 100644 --- a/pkg/stdlib/math/degrees.go +++ b/pkg/stdlib/math/degrees.go @@ -8,9 +8,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// Degrees returns the angle converted from radians to degrees. -// @param number (Float|Int) - The input number. -// @returns (Float) - The angle in degrees.l +// DEGREES returns the angle converted from radians to degrees. +// @param {Int | Float} number - The input number. +// @return {Float} - The angle in degrees func Degrees(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/math/exp.go b/pkg/stdlib/math/exp.go index 43999270..d742956e 100644 --- a/pkg/stdlib/math/exp.go +++ b/pkg/stdlib/math/exp.go @@ -9,9 +9,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// Exp returns Euler's constant (2.71828...) raised to the power of value. -// @param number (Int|Float) - Input number. -// @returns (Float) - Euler's constant raised to the power of value. +// EXP returns Euler's constant (2.71828...) raised to the power of value. +// @param {Int | Float} number - Input number. +// @return {Float} - Euler's constant raised to the power of value. func Exp(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/math/exp2.go b/pkg/stdlib/math/exp2.go index 6fec8de6..5054b9b1 100644 --- a/pkg/stdlib/math/exp2.go +++ b/pkg/stdlib/math/exp2.go @@ -9,9 +9,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// Exp2 returns 2 raised to the power of value. -// @param number (Int|Float) - Input number. -// @returns (Float) - 2 raised to the power of value. +// EXP2 returns 2 raised to the power of value. +// @param {Int | Float} number - Input number. +// @return {Float} - 2 raised to the power of value. func Exp2(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/math/floor.go b/pkg/stdlib/math/floor.go index f821c758..d1ef2d4d 100644 --- a/pkg/stdlib/math/floor.go +++ b/pkg/stdlib/math/floor.go @@ -9,9 +9,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// Floor returns the greatest integer value less than or equal to a given value. -// @param number (Int|Float) - Input number. -// @returns (Int) - The greatest integer value less than or equal to a given value. +// FLOOR returns the greatest integer value less than or equal to a given value. +// @param {Int | Float} number - Input number. +// @return {Int} - The greatest integer value less than or equal to a given value. func Floor(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/math/log.go b/pkg/stdlib/math/log.go index 5058717b..7a1e02b9 100644 --- a/pkg/stdlib/math/log.go +++ b/pkg/stdlib/math/log.go @@ -9,9 +9,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// Log returns the natural logarithm of a given value. -// @param number (Int|Float) - Input number. -// @returns (Float) - The natural logarithm of a given value. +// LOG returns the natural logarithm of a given value. +// @param {Int | Float} number - Input number. +// @return {Float} - The natural logarithm of a given value. func Log(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/math/log10.go b/pkg/stdlib/math/log10.go index f2ffc3b1..9f5bb87e 100644 --- a/pkg/stdlib/math/log10.go +++ b/pkg/stdlib/math/log10.go @@ -9,9 +9,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// Log10 returns the decimal logarithm of a given value. -// @param number (Int|Float) - Input number. -// @returns (Float) - The decimal logarithm of a given value. +// LOG10 returns the decimal logarithm of a given value. +// @param {Int | Float} number - Input number. +// @return {Float} - The decimal logarithm of a given value. func Log10(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/math/log2.go b/pkg/stdlib/math/log2.go index 3caa9f1c..477afef8 100644 --- a/pkg/stdlib/math/log2.go +++ b/pkg/stdlib/math/log2.go @@ -9,9 +9,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// Log2 returns the binary logarithm of a given value. -// @param number (Int|Float) - Input number. -// @returns (Float) - The binary logarithm of a given value. +// LOG2 returns the binary logarithm of a given value. +// @param {Int | Float} number - Input number. +// @return {Float} - The binary logarithm of a given value. func Log2(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/math/max.go b/pkg/stdlib/math/max.go index 77677b21..4da5ec38 100644 --- a/pkg/stdlib/math/max.go +++ b/pkg/stdlib/math/max.go @@ -8,9 +8,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// Max returns the greatest (arithmetic mean) of the values in array. -// @param array (Array) - Array of numbers. -// @returns (Float) - The greatest of the values in array. +// MAX returns the greatest (arithmetic mean) of the values in array. +// @param {Int[] | Float[]} array - Array of numbers. +// @return {Float} - The greatest of the values in array. func Max(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/math/median.go b/pkg/stdlib/math/median.go index 4cc2332c..159e562d 100644 --- a/pkg/stdlib/math/median.go +++ b/pkg/stdlib/math/median.go @@ -9,9 +9,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// Median returns the median of the values in array. -// @param array (Array) - Array of numbers. -// @returns (Float) - The median of the values in array. +// MEDIAN returns the median of the values in array. +// @param {Int[] | Float[]} array - Array of numbers. +// @return {Float} - The median of the values in array. func Median(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/math/min.go b/pkg/stdlib/math/min.go index 931cee44..731095d1 100644 --- a/pkg/stdlib/math/min.go +++ b/pkg/stdlib/math/min.go @@ -8,9 +8,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// Min returns the smallest (arithmetic mean) of the values in array. -// @param array (Array) - Array of numbers. -// @returns (Float) - The smallest of the values in array. +// MIN returns the smallest (arithmetic mean) of the values in array. +// @param {Int[] | Float[]} array - Array of numbers. +// @return {Float} - The smallest of the values in array. func Min(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/math/percentile.go b/pkg/stdlib/math/percentile.go index 7b82c632..28469a4f 100644 --- a/pkg/stdlib/math/percentile.go +++ b/pkg/stdlib/math/percentile.go @@ -10,11 +10,11 @@ import ( "github.com/pkg/errors" ) -// Percentile returns the nth percentile of the values in a given array. -// @param array (Array) - Array of numbers. -// @param numb (Int) - A number which must be between 0 (excluded) and 100 (included). -// @param method (String, optional) - "rank" (default) or "interpolation". -// @returns (Float) - The nth percentile, or null if the array is empty or only null values are contained in it or the percentile cannot be calculated. +// PERCENTILE returns the nth percentile of the values in a given array. +// @param {Int[] | Float[]} array - Array of numbers. +// @param {Int} number - A number which must be between 0 (excluded) and 100 (included). +// @param {String} [method="rank"] - "rank" or "interpolation". +// @return {Float} - The nth percentile, or null if the array is empty or only null values are contained in it or the percentile cannot be calculated. func Percentile(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 2, 3) diff --git a/pkg/stdlib/math/pi.go b/pkg/stdlib/math/pi.go index fb04582f..b962c369 100644 --- a/pkg/stdlib/math/pi.go +++ b/pkg/stdlib/math/pi.go @@ -8,8 +8,8 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values" ) -// Pi returns Pi value. -// @returns (Float) - Pi value. +// PI returns Pi value. +// @return {Float} - Pi value. func Pi(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 0, 0) diff --git a/pkg/stdlib/math/pow.go b/pkg/stdlib/math/pow.go index 043c8922..53132779 100644 --- a/pkg/stdlib/math/pow.go +++ b/pkg/stdlib/math/pow.go @@ -9,10 +9,10 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// Pow returns the base to the exponent value. -// @param base (Int|Float) - The base value. -// @param exp (Int|Float) - The exponent value. -// @returns (Float) - The exponentiated value. +// POW returns the base to the exponent value. +// @param {Int | Float} base - The base value. +// @param {Int | Float} exp - The exponent value. +// @return {Float} - The exponentiated value. func Pow(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 2, 2) diff --git a/pkg/stdlib/math/radians.go b/pkg/stdlib/math/radians.go index c56c57dc..deb95b07 100644 --- a/pkg/stdlib/math/radians.go +++ b/pkg/stdlib/math/radians.go @@ -8,9 +8,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// Radians returns the angle converted from degrees to radians. -// @param number (Float|Int) - The input number. -// @returns (Float) - The angle in radians. +// RADIANS returns the angle converted from degrees to radians. +// @param {Int | Float} number - The input number. +// @return {Float} - The angle in radians. func Radians(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/math/rand.go b/pkg/stdlib/math/rand.go index a7a53e17..a3bed91c 100644 --- a/pkg/stdlib/math/rand.go +++ b/pkg/stdlib/math/rand.go @@ -9,10 +9,10 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values" ) -// Rand return a pseudo-random number between 0 and 1. -// @param max (Float|Int, optional) - Upper limit. -// @param min (Float|Int, optional) - Lower limit. -// @returns (Float) - A number greater than 0 and less than 1. +// RAND return a pseudo-random number between 0 and 1. +// @param {Int | Float} [max] - Upper limit. +// @param {Int | Float} [min] - Lower limit. +// @return {Float} - A number greater than 0 and less than 1. func Rand(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 0, 2) diff --git a/pkg/stdlib/math/range.go b/pkg/stdlib/math/range.go index 9f65c2fe..906d086d 100644 --- a/pkg/stdlib/math/range.go +++ b/pkg/stdlib/math/range.go @@ -8,10 +8,11 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// Range returns an array of numbers in the specified range, optionally with increments other than 1. -// @param start (Int|Float) - The value to start the range at (inclusive). -// @param end (Int|Float) - The value to end the range with (inclusive). -// @param step (Int|Float, optional) - How much to increment in every step, the default is 1.0. +// RANGE returns an array of numbers in the specified range, optionally with increments other than 1. +// @param {Int | Float} start - The value to start the range at (inclusive). +// @param {Int | Float} end - The value to end the range with (inclusive). +// @param {Int | Float} [step=1.0] - How much to increment in every step. +// @return {Int[] | Float[]} - Array of numbers in the specified range, optionally with increments other than 1. func Range(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 2, 3) diff --git a/pkg/stdlib/math/round.go b/pkg/stdlib/math/round.go index 5a6a6dd7..649927f8 100644 --- a/pkg/stdlib/math/round.go +++ b/pkg/stdlib/math/round.go @@ -9,9 +9,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// Round returns the nearest integer, rounding half away from zero. -// @param number (Int|Float) - Input number. -// @returns (Int) - The nearest integer, rounding half away from zero. +// ROUND returns the nearest integer, rounding half away from zero. +// @param {Int | Float} number - Input number. +// @return {Int} - The nearest integer, rounding half away from zero. func Round(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/math/sin.go b/pkg/stdlib/math/sin.go index 6fb74db2..ea4772e3 100644 --- a/pkg/stdlib/math/sin.go +++ b/pkg/stdlib/math/sin.go @@ -9,9 +9,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// Sin returns the sine of the radian argument. -// @param number (Int|Float) - Input number. -// @returns (Float) - The sin, in radians, of a given number. +// SIN returns the sine of the radian argument. +// @param {Int | Float} number - Input number. +// @return {Float} - The sin, in radians, of a given number. func Sin(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/math/sqrt.go b/pkg/stdlib/math/sqrt.go index 7762a7d3..d72211a0 100644 --- a/pkg/stdlib/math/sqrt.go +++ b/pkg/stdlib/math/sqrt.go @@ -9,9 +9,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// Sqrt returns the square root of a given number. -// @param value (Int|Float) - A number. -// @returns (Float) - The square root. +// SQRT returns the square root of a given number. +// @param {Int | Float} value - A number. +// @return {Float} - The square root. func Sqrt(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/math/stddev_population.go b/pkg/stdlib/math/stddev_population.go index ae840eb0..d669c9cd 100644 --- a/pkg/stdlib/math/stddev_population.go +++ b/pkg/stdlib/math/stddev_population.go @@ -9,9 +9,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// StandardDeviationPopulation returns the population standard deviation of the values in a given array. -// @params (Array) - Array of numbers. -// @returns (Float) - The population standard deviation. +// STDDEV_POPULATION returns the population standard deviation of the values in a given array. +// @param {Int[] | Float[]} numbers - Array of numbers. +// @return {Float} - The population standard deviation. func StandardDeviationPopulation(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/math/stddev_sample.go b/pkg/stdlib/math/stddev_sample.go index 89f6f5df..22ceedaa 100644 --- a/pkg/stdlib/math/stddev_sample.go +++ b/pkg/stdlib/math/stddev_sample.go @@ -9,9 +9,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// StandardDeviationSample returns the sample standard deviation of the values in a given array. -// @params (Array) - Array of numbers. -// @returns (Float) - The sample standard deviation. +// STDDEV_SAMPLE returns the sample standard deviation of the values in a given array. +// @param {Int[] | Float[]} numbers - Array of numbers. +// @return {Float} - The sample standard deviation. func StandardDeviationSample(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/math/sum.go b/pkg/stdlib/math/sum.go index 93ecda97..9a7c3681 100644 --- a/pkg/stdlib/math/sum.go +++ b/pkg/stdlib/math/sum.go @@ -8,9 +8,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// Sum returns the sum of the values in a given array. -// @param array (Array) - Array of numbers. -// @returns (Float) - The sum of the values. +// SUM returns the sum of the values in a given array. +// @param {Int[] | Float[]} numbers - Array of numbers. +// @return {Float} - The sum of the values. func Sum(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/math/tan.go b/pkg/stdlib/math/tan.go index 731a2c57..c73216de 100644 --- a/pkg/stdlib/math/tan.go +++ b/pkg/stdlib/math/tan.go @@ -9,9 +9,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// Tan returns the tangent of a given number. -// @param value (Int|Float) - A number. -// @returns (Float) - The tangent. +// TAN returns the tangent of a given number. +// @param {Int | Float} number - A number. +// @return {Float} - The tangent. func Tan(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/math/variance_population.go b/pkg/stdlib/math/variance_population.go index e876f2d8..13442938 100644 --- a/pkg/stdlib/math/variance_population.go +++ b/pkg/stdlib/math/variance_population.go @@ -9,9 +9,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// PopulationVariance returns the population variance of the values in a given array. -// @params (Array) - Array of numbers. -// @returns (Float) - The population variance. +// VARIANCE_POPULATION returns the population variance of the values in a given array. +// @param {Int[] | Float[]} numbers - Array of numbers. +// @return {Float} - The population variance. func PopulationVariance(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/math/variance_sample.go b/pkg/stdlib/math/variance_sample.go index 0cccad90..525d97c6 100644 --- a/pkg/stdlib/math/variance_sample.go +++ b/pkg/stdlib/math/variance_sample.go @@ -9,9 +9,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// SampleVariance returns the sample variance of the values in a given array. -// @params (Array) - Array of numbers. -// @returns (Float) - The sample variance. +// VARIANCE_SAMPLE returns the sample variance of the values in a given array. +// @param {Int[] | Float[]} numbers - Array of numbers. +// @return {Float} - The sample variance. func SampleVariance(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/objects/has.go b/pkg/stdlib/objects/has.go index 5084a5b5..5ee773e4 100644 --- a/pkg/stdlib/objects/has.go +++ b/pkg/stdlib/objects/has.go @@ -8,9 +8,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// Has returns the value stored by the given key. -// @params (String) - The key name string. -// @returns (Boolean) - True if the key exists else false. +// HAS returns the value stored by the given key. +// @param {String} key - The key name string. +// @return {Boolean} - True if the key exists else false. func Has(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 2, 2) diff --git a/pkg/stdlib/objects/keep_keys.go b/pkg/stdlib/objects/keep_keys.go index 5d0f300f..f32fa734 100644 --- a/pkg/stdlib/objects/keep_keys.go +++ b/pkg/stdlib/objects/keep_keys.go @@ -8,10 +8,10 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// KeepKeys returns a new object with only given keys. -// @params src (Object) - source object. -// @params keys (Array Of String OR Strings) - keys that need to be keeped. -// @returns (Object) - New Object with only given keys. +// KEEP_KEYS returns a new object with only given keys. +// @param {Object} obj - Source object. +// @param {String, repeated} keys - Keys that need to be kept. +// @return {Object} - New Object with only given keys. func KeepKeys(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 2, core.MaxArgs) diff --git a/pkg/stdlib/objects/keys.go b/pkg/stdlib/objects/keys.go index 65cd1531..72c5b028 100644 --- a/pkg/stdlib/objects/keys.go +++ b/pkg/stdlib/objects/keys.go @@ -9,10 +9,10 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// Keys returns string array of object's keys -// @params obj (Object) - The object whose keys you want to extract -// @params sort (Boolean, optional) - If sort is true, then the returned keys will be sorted. -// @returns (Array of String) - Array that contains object keys. +// KEYS returns string array of object's keys +// @param {Object} obj - The object whose keys you want to extract +// @param {Boolean} [sort=False] - If sort is true, then the returned keys will be sorted. +// @return {String[]} - Array that contains object keys. func Keys(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 2) if err != nil { diff --git a/pkg/stdlib/objects/merge.go b/pkg/stdlib/objects/merge.go index 3ee42708..4712a908 100644 --- a/pkg/stdlib/objects/merge.go +++ b/pkg/stdlib/objects/merge.go @@ -8,9 +8,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// Merge merge the given objects into a single object. -// @params objs (Array Of Object OR Objects) - objects to merge. -// @returns (Object) - Object created by merging. +// MERGE merge the given objects into a single object. +// @param {Object, repeated} objects - Objects to merge. +// @return {Object} - Object created by merging. func Merge(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, core.MaxArgs) diff --git a/pkg/stdlib/objects/merge_recursive.go b/pkg/stdlib/objects/merge_recursive.go index a5e7a7ba..10552b25 100644 --- a/pkg/stdlib/objects/merge_recursive.go +++ b/pkg/stdlib/objects/merge_recursive.go @@ -8,9 +8,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// MergeRecursive recursively merge the given objects into a single object. -// @params objs (Objects) - objects to merge. -// @returns (Object) - Object created by merging. +// MERGE_RECURSIVE recursively merge the given objects into a single object. +// @param {Objects, repeated} objects - Objects to merge. +// @return {Object} - Object created by merging. func MergeRecursive(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, core.MaxArgs) if err != nil { diff --git a/pkg/stdlib/objects/values.go b/pkg/stdlib/objects/values.go index e31654b4..631a3a94 100644 --- a/pkg/stdlib/objects/values.go +++ b/pkg/stdlib/objects/values.go @@ -8,9 +8,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// Values return the attribute values of the object as an array. -// @params obj (Object) - an object. -// @returns (Array of Value) - the values of document returned in any order. +// VALUES return the attribute values of the object as an array. +// @param {Object} object - Target object. +// @return {Any[]} - Values of document returned in any order. func Values(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/objects/zip.go b/pkg/stdlib/objects/zip.go index 4a7a64f6..0f0a0256 100644 --- a/pkg/stdlib/objects/zip.go +++ b/pkg/stdlib/objects/zip.go @@ -9,11 +9,11 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// Zip returns an object assembled from the separate parameters keys and values. +// ZIP returns an object assembled from the separate parameters keys and values. // Keys and values must be arrays and have the same length. -// @params keys (Array of Strings) - an array of strings, to be used as key names in the result. -// @params values (Array of Objects) - an array of core.Value, to be used as key values. -// @returns (Object) - an object with the keys and values assembled. +// @param {String[]} keys - An array of strings, to be used as key names in the result. +// @param {Object[]} values - An array of core.Value, to be used as key values. +// @return {Object} - An object with the keys and values assembled. func Zip(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 2, 2) diff --git a/pkg/stdlib/path/base.go b/pkg/stdlib/path/base.go index 3e33544b..41c22203 100644 --- a/pkg/stdlib/path/base.go +++ b/pkg/stdlib/path/base.go @@ -9,10 +9,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// Base returns the last component of the path. -// or the path itself if it does not contain any directory separators. -// @params path (String) - The path. -// @returns (String) - The last component of the path. +// BASE returns the last component of the path or the path itself if it does not contain any directory separators. +// @param {String} path - The path. +// @return {String} - The last component of the path. func Base(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/path/clean.go b/pkg/stdlib/path/clean.go index 94b64cca..f3c9d404 100644 --- a/pkg/stdlib/path/clean.go +++ b/pkg/stdlib/path/clean.go @@ -9,9 +9,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// Clean returns the shortest path name equivalent to path. -// @params path (String) - The path. -// @returns (String) - The shortest path name equivalent to path +// CLEAN returns the shortest path name equivalent to path. +// @param {String} path - The path. +// @return {String} - The shortest path name equivalent to path func Clean(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/path/dir.go b/pkg/stdlib/path/dir.go index 297d08b1..b38f744a 100644 --- a/pkg/stdlib/path/dir.go +++ b/pkg/stdlib/path/dir.go @@ -9,9 +9,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// Dir returns the directory component of path. -// @params path (String) - The path. -// @returns (String) - The directory component of path. +// DIR returns the directory component of path. +// @param {String} path - The path. +// @return {String} - The directory component of path. func Dir(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/path/ext.go b/pkg/stdlib/path/ext.go index d2516bc4..cf6b3122 100644 --- a/pkg/stdlib/path/ext.go +++ b/pkg/stdlib/path/ext.go @@ -9,9 +9,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// Ext returns the extension of the last component of path. -// @params path (String) - The path. -// @returns (String) - The extension of the last component of path. +// EXT returns the extension of the last component of path. +// @param {String} path - The path. +// @return {String} - The extension of the last component of path. func Ext(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/path/is_abs.go b/pkg/stdlib/path/is_abs.go index 6a8a212e..d922e0ff 100644 --- a/pkg/stdlib/path/is_abs.go +++ b/pkg/stdlib/path/is_abs.go @@ -9,9 +9,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// IsAbs reports whether the path is absolute. -// @params path (String) - The path. -// @returns (Boolean) - True if the path is absolute. +// IS_ABS reports whether the path is absolute. +// @param {String} path - The path. +// @return {Boolean} - True if the path is absolute. func IsAbs(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/path/join.go b/pkg/stdlib/path/join.go index e7f93e46..51f852a3 100644 --- a/pkg/stdlib/path/join.go +++ b/pkg/stdlib/path/join.go @@ -9,9 +9,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// Join joins any number of path elements into a single path, separating them with slashes. -// @param elem (String...|Array) - The path elements -// @returns (String) - Single path from the given elements. +// JOIN joins any number of path elements into a single path, separating them with slashes. +// @param {String, repeated | String[]} elements - The path elements +// @return {String} - Single path from the given elements. func Join(_ context.Context, args ...core.Value) (core.Value, error) { argsCount := len(args) diff --git a/pkg/stdlib/path/lib.go b/pkg/stdlib/path/lib.go index 7b8dad66..54252770 100644 --- a/pkg/stdlib/path/lib.go +++ b/pkg/stdlib/path/lib.go @@ -3,6 +3,7 @@ package path import "github.com/MontFerret/ferret/pkg/runtime/core" // RegisterLib register `PATH` namespace functions. +// @namespace PATH func RegisterLib(ns core.Namespace) error { return ns. Namespace("PATH"). diff --git a/pkg/stdlib/path/match.go b/pkg/stdlib/path/match.go index 803ab93a..10180f07 100644 --- a/pkg/stdlib/path/match.go +++ b/pkg/stdlib/path/match.go @@ -9,10 +9,10 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// Match reports whether name matches the pattern. -// @param pattern (String) - The pattern. -// @param name (String) - The name. -// @returns (Boolean) - True if the name matches the pattern. +// MATCH reports whether name matches the pattern. +// @param {String} pattern - The pattern. +// @param {String} name - The name. +// @return {Boolean} - True if the name matches the pattern. func Match(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 2, 2) diff --git a/pkg/stdlib/path/separate.go b/pkg/stdlib/path/separate.go index e9072e00..c8c37d9b 100644 --- a/pkg/stdlib/path/separate.go +++ b/pkg/stdlib/path/separate.go @@ -9,9 +9,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// Separate separates the path into a directory and filename component. -// @param path (String) - The path -// @returns (Array) - First item is a directory component, and second is a filename component. +// SEPARATE separates the path into a directory and filename component. +// @param {String} path - The path +// @return {Any[]} - First item is a directory component, and second is a filename component. func Separate(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/strings/case.go b/pkg/stdlib/strings/case.go index 63a43d96..3a571ce8 100644 --- a/pkg/stdlib/strings/case.go +++ b/pkg/stdlib/strings/case.go @@ -8,9 +8,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values" ) -// Lower converts strings to their lower-case counterparts. All other characters are returned unchanged. -// @param src (String) - The source string. -// @returns (String) - THis string in lower case. +// LOWER converts strings to their lower-case counterparts. All other characters are returned unchanged. +// @param {String} str - The source string. +// @return {String} - THis string in lower case. func Lower(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) @@ -23,9 +23,9 @@ func Lower(_ context.Context, args ...core.Value) (core.Value, error) { return values.NewString(text), nil } -// Upper converts strings to their upper-case counterparts. All other characters are returned unchanged. -// @param src (String) - The source string. -// @returns (String) - THis string in upper case. +// UPPER converts strings to their upper-case counterparts. All other characters are returned unchanged. +// @param {String} str - The source string. +// @return {String} - THis string in upper case. func Upper(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/strings/concat.go b/pkg/stdlib/strings/concat.go index 0b326bbb..59300605 100644 --- a/pkg/stdlib/strings/concat.go +++ b/pkg/stdlib/strings/concat.go @@ -8,9 +8,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// Concat concatenates one or more instances of Read, or an Array. -// @params src (String...|Array) - The source string / array. -// @returns String +// CONCAT concatenates one or more instances of String, or an Array. +// @param {String, repeated | String[]} src - The source string / array. +// @return {String} - A string value. func Concat(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, core.MaxArgs) @@ -41,10 +41,10 @@ func Concat(_ context.Context, args ...core.Value) (core.Value, error) { return res, nil } -// ConcatWithSeparator concatenates one or more instances of Read, or an Array with a given separator. -// @params separator (string) - The separator string. -// @params src (string...|array) - The source string / array. -// @returns string +// CONCAT_SEPARATOR concatenates one or more instances of String, or an Array with a given separator. +// @param {String} separator - The separator string. +// @param {String, repeated | String[]} src - The source string / array. +// @return {String} - Concatenated string. func ConcatWithSeparator(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 2, core.MaxArgs) diff --git a/pkg/stdlib/strings/contains.go b/pkg/stdlib/strings/contains.go index c82c88b7..b20440c5 100644 --- a/pkg/stdlib/strings/contains.go +++ b/pkg/stdlib/strings/contains.go @@ -8,12 +8,11 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// Contains returns a value indicating whether a specified substring occurs within a string. -// @param src (String) - The source string. -// @param search (String) - The string to seek. -// @param returnIndex (Boolean) - Values which indicates whether to return the character position of the match is returned instead of a boolean. -// The default is false. -// @returns (Boolean|Int) +// CONTAINS returns a value indicating whether a specified substring occurs within a string. +// @param {String} str - The source string. +// @param {String} search - The string to seek. +// @param {Boolean} [returnIndex=False] - Values which indicates whether to return the character position of the match is returned instead of a boolean. +// @return {Boolean | Int} - A value indicating whether a specified substring occurs within a string. func Contains(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 2, 3) diff --git a/pkg/stdlib/strings/decode.go b/pkg/stdlib/strings/decode.go index 27a2f8fa..5cbd4df1 100644 --- a/pkg/stdlib/strings/decode.go +++ b/pkg/stdlib/strings/decode.go @@ -11,9 +11,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/core" ) -// FromBase64 returns the value of a base64 representation. -// @param base64String (String) - The string to decode. -// @returns value (String) - The decoded string. +// FROM_BASE64 returns the value of a base64 representation. +// @param {String} str - The string to decode. +// @return {String} - The decoded string. func FromBase64(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) @@ -31,9 +31,9 @@ func FromBase64(_ context.Context, args ...core.Value) (core.Value, error) { return values.NewString(string(out)), nil } -// DecodeURIComponent returns the decoded String of uri. -// @param (String) - Uri to decode. -// @returns String - Decoded string. +// DECODE_URI_COMPONENT returns the decoded String of uri. +// @param {String} uri - Uri to decode. +// @return {String} - Decoded string. func DecodeURIComponent(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/strings/encode.go b/pkg/stdlib/strings/encode.go index d38b0438..5fd884b4 100644 --- a/pkg/stdlib/strings/encode.go +++ b/pkg/stdlib/strings/encode.go @@ -12,9 +12,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values" ) -// EncodeURIComponent returns the encoded String of uri. -// @param (String) - Uri to encode. -// @returns String - Encoded string. +// ENCODE_URI_COMPONENT returns the encoded String of uri. +// @param {String} uri - Uri to encode. +// @return {String} - Encoded string. func EncodeURIComponent(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) @@ -27,9 +27,9 @@ func EncodeURIComponent(_ context.Context, args ...core.Value) (core.Value, erro return values.NewString(str), nil } -// Md5 calculates the MD5 checksum for text and return it in a hexadecimal string representation. -// @param text (String) - The string to do calculations against to. -// @return (String) - MD5 checksum as hex string. +// MD5 calculates the MD5 checksum for text and return it in a hexadecimal string representation. +// @param {String} str - The string to do calculations against to. +// @return {String} - MD5 checksum as hex string. func Md5(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) @@ -43,9 +43,9 @@ func Md5(_ context.Context, args ...core.Value) (core.Value, error) { return values.NewString(string(res[:])), nil } -// Sha1 calculates the SHA1 checksum for text and returns it in a hexadecimal string representation. -// @param text (String) - The string to do calculations against to. -// @return (String) - Sha1 checksum as hex string. +// SHA1 calculates the SHA1 checksum for text and returns it in a hexadecimal string representation. +// @param {String} str - The string to do calculations against to. +// @return {String} - Sha1 checksum as hex string. func Sha1(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) @@ -59,9 +59,9 @@ func Sha1(_ context.Context, args ...core.Value) (core.Value, error) { return values.NewString(string(res[:])), nil } -// Sha512 calculates the SHA512 checksum for text and returns it in a hexadecimal string representation. -// @param text (String) - The string to do calculations against to. -// @return (String) - SHA512 checksum as hex string. +// SHA512 calculates the SHA512 checksum for text and returns it in a hexadecimal string representation. +// @param {String} str - The string to do calculations against to. +// @return {String} - SHA512 checksum as hex string. func Sha512(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) @@ -75,9 +75,9 @@ func Sha512(_ context.Context, args ...core.Value) (core.Value, error) { return values.NewString(string(res[:])), nil } -// ToBase64 returns the base64 representation of value. -// @param value (string) - The string to encode. -// @returns toBase64String (String) - A base64 representation of the string. +// TO_BASE64 returns the base64 representation of value. +// @param {String} str - The string to encode. +// @return {String} - A base64 representation of the string. func ToBase64(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/strings/escape.go b/pkg/stdlib/strings/escape.go index fc65b7fd..5ef3c0d6 100644 --- a/pkg/stdlib/strings/escape.go +++ b/pkg/stdlib/strings/escape.go @@ -8,12 +8,12 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values" ) -// EscapeHTML escapes special characters like "<" to become "<". It +// ESCAPE_HTML escapes special characters like "<" to become "<". It // escapes only five such characters: <, >, &, ' and ". // UnescapeString(EscapeString(s)) == s always holds, but the converse isn't // always true. -// @param (String) - Uri to escape. -// @returns String - Escaped string. +// @param {String} uri - Uri to escape. +// @return {String} - Escaped string. func EscapeHTML(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/strings/find.go b/pkg/stdlib/strings/find.go index 99304aa0..1599fb99 100644 --- a/pkg/stdlib/strings/find.go +++ b/pkg/stdlib/strings/find.go @@ -9,13 +9,12 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// FindFirst returns the position of the first occurrence of the string search inside the string text. Positions start at 0. -// @param src (String) - The source string. -// @param search (String) - The string to seek. -// @param start (Int, optional) - Limit the search to a subset of the text, beginning at start. -// @param end (Int, optional) - Limit the search to a subset of the text, ending at end -// @returns (Int) - The character position of the match. -// If search is not contained in text, -1 is returned. If search is empty, start is returned. +// FIND_FIRST returns the position of the first occurrence of the string search inside the string text. Positions start at 0. +// @param {String} str - The source string. +// @param {String} search - The string to seek. +// @param {Int} [start] - Limit the search to a subset of the text, beginning at start. +// @param {Int} [end] - Limit the search to a subset of the text, ending at end +// @return {Int} - The character position of the match. If search is not contained in text, -1 is returned. If search is empty, start is returned. func FindFirst(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 2, 4) @@ -56,13 +55,12 @@ func FindFirst(_ context.Context, args ...core.Value) (core.Value, error) { return values.NewInt(found), nil } -// FindLast returns the position of the last occurrence of the string search inside the string text. Positions start at 0. -// @param src (String) - The source string. -// @param search (String) - The string to seek. -// @param start (Int, optional) - Limit the search to a subset of the text, beginning at start. -// @param end (Int, optional) - Limit the search to a subset of the text, ending at end -// @returns (Int) - The character position of the match. -// If search is not contained in text, -1 is returned. If search is empty, start is returned. +// FIND_LAST returns the position of the last occurrence of the string search inside the string text. Positions start at 0. +// @param {String} src - The source string. +// @param {String} search - The string to seek. +// @param {Int} [start] - Limit the search to a subset of the text, beginning at start. +// @param {Int} [end] - Limit the search to a subset of the text, ending at end +// @return {Int} - The character position of the match. If search is not contained in text, -1 is returned. If search is empty, start is returned. func FindLast(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 2, 4) diff --git a/pkg/stdlib/strings/fmt.go b/pkg/stdlib/strings/fmt.go index 403a19d7..244b2a79 100644 --- a/pkg/stdlib/strings/fmt.go +++ b/pkg/stdlib/strings/fmt.go @@ -12,10 +12,10 @@ import ( "github.com/pkg/errors" ) -// Fmt formats the template using these arguments. -// @params template (String) - template. -// @params args (Any Values) - template arguments. -// @returns (String) - string formed by template using arguments. +// FMT formats the template using these arguments. +// @param {String} template - template. +// @param {Any, repeated} args - template arguments. +// @return {String} - string formed by template using arguments. func Fmt(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, core.MaxArgs) if err != nil { diff --git a/pkg/stdlib/strings/json.go b/pkg/stdlib/strings/json.go index da60a04a..4b2a05a0 100644 --- a/pkg/stdlib/strings/json.go +++ b/pkg/stdlib/strings/json.go @@ -8,9 +8,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values" ) -// JSONParse returns a FQL value described by the JSON-encoded input string. -// @params text (String) - The string to parse as JSON. -// @returns FQL value (Read) +// JSON_PARSE returns a value described by the JSON-encoded input string. +// @param {String} str - The string to parse as JSON. +// @return {Any} - Parsed value. func JSONParse(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) @@ -29,9 +29,9 @@ func JSONParse(_ context.Context, args ...core.Value) (core.Value, error) { return values.Parse(val), nil } -// JSONStringify returns a JSON string representation of the input value. -// @params value (Read) - The input value to serialize. -// @returns json (String) +// JSON_STRINGIFY returns a JSON string representation of the input value. +// @param {Any} str - The input value to serialize. +// @return {String} - JSON string. func JSONStringify(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/strings/lib.go b/pkg/stdlib/strings/lib.go index 3d32e7b2..ac14d84b 100644 --- a/pkg/stdlib/strings/lib.go +++ b/pkg/stdlib/strings/lib.go @@ -21,10 +21,6 @@ func RegisterLib(ns core.Namespace) error { "LTRIM": LTrim, "RANDOM_TOKEN": RandomToken, "MD5": Md5, - "REGEXP_MATCH": RegexMatch, // Deprecated - "REGEXP_SPLIT": RegexSplit, // Deprecated - "REGEXP_TEST": RegexTest, // Deprecated - "REGEXP_REPLACE": RegexReplace, // Deprecated "REGEX_MATCH": RegexMatch, "REGEX_SPLIT": RegexSplit, "REGEX_TEST": RegexTest, diff --git a/pkg/stdlib/strings/like.go b/pkg/stdlib/strings/like.go index 6d94dbe0..e50b10d9 100644 --- a/pkg/stdlib/strings/like.go +++ b/pkg/stdlib/strings/like.go @@ -8,11 +8,11 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values" ) -// Like checks whether the pattern search is contained in the string text, using wildcard matching. -// @param text (String) - The string to search in. -// @param search (String) - A search pattern that can contain the wildcard characters. -// @param caseInsensitive (Boolean) - If set to true, the matching will be case-insensitive. The default is false. -// @return (Boolean) - Returns true if the pattern is contained in text, and false otherwise. +// LIKE checks whether the pattern search is contained in the string text, using wildcard matching. +// @param {String} str - The string to search in. +// @param {String} search - A search pattern that can contain the wildcard characters. +// @param {Boolean} caseInsensitive - If set to true, the matching will be case-insensitive. The default is false. +// @return {Boolean} - Returns true if the pattern is contained in text, and false otherwise. func Like(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 2, 3) diff --git a/pkg/stdlib/strings/random.go b/pkg/stdlib/strings/random.go index aba604f2..f60a832f 100644 --- a/pkg/stdlib/strings/random.go +++ b/pkg/stdlib/strings/random.go @@ -21,9 +21,9 @@ const ( // https://github.com/golang/go/issues/8926 var randSrc = rand.NewSource(time.Now().UnixNano()) -// RandomToken generates a pseudo-random token string with the specified length. The algorithm for token generation should be treated as opaque. -// @param length (Int) - The desired string length for the token. It must be greater than 0 and at most 65536. -// @return (String) - A generated token consisting of lowercase letters, uppercase letters and numbers. +// RANDOM_TOKEN generates a pseudo-random token string with the specified length. The algorithm for token generation should be treated as opaque. +// @param {Int} len - The desired string length for the token. It must be greater than 0 and at most 65536. +// @return {String} - A generated token consisting of lowercase letters, uppercase letters and numbers. func RandomToken(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/strings/regex.go b/pkg/stdlib/strings/regex.go index e1d6f301..0919272d 100644 --- a/pkg/stdlib/strings/regex.go +++ b/pkg/stdlib/strings/regex.go @@ -9,11 +9,11 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// RegexMatch returns the matches in the given string text, using the regex. -// @param text (String) - The string to search in. -// @param regex (String) - A regular expression to use for matching the text. -// @param caseInsensitive (Boolean) - If set to true, the matching will be case-insensitive. The default is false. -// @return (Array) - An array of strings containing the matches. +// REGEX_MATCH returns the matches in the given string text, using the regex. +// @param {String} str - The string to search in. +// @param {String} expression - A regular expression to use for matching the text. +// @param {Boolean} caseInsensitive - If set to true, the matching will be case-insensitive. The default is false. +// @return {Any[]} - An array of strings containing the matches. func RegexMatch(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 2, 3) @@ -50,12 +50,12 @@ func RegexMatch(_ context.Context, args ...core.Value) (core.Value, error) { return res, nil } -// RegexSplit splits the given string text into a list of strings, using the separator. -// @param text (String) - The string to split. -// @param regex (String) - A regular expression to use for splitting the text. -// @param caseInsensitive (Boolean) - If set to true, the matching will be case-insensitive. The default is false. -// @param limit (Int) - Limit the number of split values in the result. If no limit is given, the number of splits returned is not bounded. -// @return (Array) - An array of strings splited by the expression. +// REGEX_SPLIT splits the given string text into a list of strings, using the separator. +// @param {String} str - The string to split. +// @param {String} expression - A regular expression to use for splitting the text. +// @param {Boolean} caseInsensitive - If set to true, the matching will be case-insensitive. The default is false. +// @param {Int} limit - Limit the number of split values in the result. If no limit is given, the number of splits returned is not bounded. +// @return {Any[]} - An array of strings splitted by the expression. func RegexSplit(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 2, 4) @@ -93,11 +93,11 @@ func RegexSplit(_ context.Context, args ...core.Value) (core.Value, error) { return res, nil } -// RegexTest test whether the regexp has at least one match in the given text. -// @param text (String) - The string to split. -// @param regex (String) - A regular expression to use for splitting the text. -// @param caseInsensitive (Boolean) - If set to true, the matching will be case-insensitive. The default is false. -// @return (Boolean) - Returns true if the pattern is contained in text, and false otherwise. +// REGEX_TEST test whether the regexp has at least one match in the given text. +// @param {String} str - The string to test. +// @param {String} expression - A regular expression to use for splitting the text. +// @param {Boolean} [caseInsensitive=False] - If set to true, the matching will be case-insensitive. +// @return {Boolean} - Returns true if the pattern is contained in text, and false otherwise. func RegexTest(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 2, 3) @@ -125,12 +125,12 @@ func RegexTest(_ context.Context, args ...core.Value) (core.Value, error) { return values.NewBoolean(matches), nil } -// RegexReplace replace every substring matched with the regexp with a given string. -// @param text (String) - The string to split. -// @param regex (String) - A regular expression search pattern. -// @param replacement (String) - The string to replace the search pattern with -// @param caseInsensitive (Boolean) - If set to true, the matching will be case-insensitive. The default is false. -// @return (String) - Returns the string text with the search regex pattern replaced with the replacement string wherever the pattern exists in text +// REGEX_REPLACE replace every substring matched with the regexp with a given string. +// @param {String} str - The string to split. +// @param {String} expression - A regular expression search pattern. +// @param {String} replacement - The string to replace the search pattern with +// @param {Boolean} [caseInsensitive=False] - If set to true, the matching will be case-insensitive. +// @return {String} - Returns the string text with the search regex pattern replaced with the replacement string wherever the pattern exists in text func RegexReplace(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 3, 4) diff --git a/pkg/stdlib/strings/split.go b/pkg/stdlib/strings/split.go index fbfdaed9..b822b912 100644 --- a/pkg/stdlib/strings/split.go +++ b/pkg/stdlib/strings/split.go @@ -9,11 +9,11 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// Split splits the given string value into a list of strings, using the separator. -// @params text (String) - The string to split. -// @params separator (String) - The separator. -// @params limit (Int) - Limit the number of split values in the result. If no limit is given, the number of splits returned is not bounded. -// @returns strings (Array) - Array of strings. +// SPLIT splits the given string value into a list of strings, using the separator. +// @param {String} str - The string to split. +// @param {String} separator - The separator. +// @param {Int} limit - Limit the number of split values in the result. If no limit is given, the number of splits returned is not bounded. +// @return {String[]} - Array of strings. func Split(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 2, 3) diff --git a/pkg/stdlib/strings/substitute.go b/pkg/stdlib/strings/substitute.go index 1bd1be91..cdb5c310 100644 --- a/pkg/stdlib/strings/substitute.go +++ b/pkg/stdlib/strings/substitute.go @@ -9,12 +9,12 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// Substitute replaces search values in the string value. -// @params text (String) - The string to modify -// @params search (String) - The string representing a search pattern -// @params replace (String) - The string representing a replace value -// @param limit (Int) - The cap the number of replacements to this value. -// @return (String) - Returns a string with replace substring. +// SUBSTITUTE replaces search values in the string value. +// @param {String} str - The string to modify +// @param {String} search - The string representing a search pattern +// @param {String} replace - The string representing a replace value +// @param {Int} limit - The cap the number of replacements to this value. +// @return {String} - Returns a string with replace substring. func Substitute(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 2, 4) diff --git a/pkg/stdlib/strings/substr.go b/pkg/stdlib/strings/substr.go index d1d9eb75..65d26827 100644 --- a/pkg/stdlib/strings/substr.go +++ b/pkg/stdlib/strings/substr.go @@ -8,11 +8,11 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// Substring returns a substring of value. -// @params value (String) - The source string. -// @param offset (Int) - Start at offset, offsets start at position 0. -// @param length (Int, optional) - At most length characters, omit to get the substring from offset to the end of the string. Optional. -// @returns substring (String) - A substring of value. +// SUBSTRING returns a substring of value. +// @param {String} str - The source string. +// @param {Int} offset - Start at offset, offsets start at position 0. +// @param {Int} [length] - At most length characters, omit to get the substring from offset to the end of the string. +// @return {String} - A substring of value. func Substring(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 2, 3) @@ -55,10 +55,10 @@ func Substring(_ context.Context, args ...core.Value) (core.Value, error) { return values.NewStringFromRunes(substr), nil } -// Left returns the leftmost characters of the string value by index. -// @param src (String) - The source string. -// @params length (Int) - The amount of characters to return. -// @returns substr (String) +// LEFT returns the leftmost characters of the string value by index. +// @param {String} str - The source string. +// @param {Int} length - The amount of characters to return. +// @return {String} - The leftmost characters of the string value by index. func Left(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 2, 2) @@ -82,10 +82,10 @@ func Left(_ context.Context, args ...core.Value) (core.Value, error) { return values.NewStringFromRunes(runes[0:pos]), nil } -// Right returns the rightmost characters of the string value. -// @param src (String) - The source string. -// @params length (Int) - The amount of characters to return. -// @returns substr (String) +// RIGHT returns the rightmost characters of the string value. +// @param {String} str - The source string. +// @param {Int} length - The amount of characters to return. +// @return {String} - The rightmost characters of the string value. func Right(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 2, 2) diff --git a/pkg/stdlib/strings/trim.go b/pkg/stdlib/strings/trim.go index c9a15be7..a68d704e 100644 --- a/pkg/stdlib/strings/trim.go +++ b/pkg/stdlib/strings/trim.go @@ -8,10 +8,10 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values" ) -// Trim returns the string value with whitespace stripped from the start and/or end. -// @param value (String) - The string. -// @param chars (String) - Overrides the characters that should be removed from the string. It defaults to \r\n \t. -// @returns (String) - The string without chars on both sides. +// TRIM returns the string value with whitespace stripped from the start and/or end. +// @param {String} str - The string. +// @param {String} chars - Overrides the characters that should be removed from the string. It defaults to \r\n \t. +// @return {String} - The string without chars on both sides. func Trim(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 2) @@ -28,10 +28,10 @@ func Trim(_ context.Context, args ...core.Value) (core.Value, error) { return values.NewString(strings.TrimSpace(text)), nil } -// LTrim returns the string value with whitespace stripped from the start only. -// @param value (String) - The string. -// @param chars (String) - Overrides the characters that should be removed from the string. It defaults to \r\n \t. -// @returns (String) - The string without chars at the left-hand side. +// LTRIM returns the string value with whitespace stripped from the start only. +// @param {String} str - The string. +// @param {String} chars - Overrides the characters that should be removed from the string. It defaults to \r\n \t. +// @return {String} - The string without chars at the left-hand side. func LTrim(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 2) @@ -49,10 +49,10 @@ func LTrim(_ context.Context, args ...core.Value) (core.Value, error) { return values.NewString(strings.TrimLeft(text, chars)), nil } -// RTrim returns the string value with whitespace stripped from the end only. -// @param value (String) - The string. -// @param chars (String) - Overrides the characters that should be removed from the string. It defaults to \r\n \t. -// @returns (String) - The string without chars at the right-hand side. +// RTRIM returns the string value with whitespace stripped from the end only. +// @param {String} str - The string. +// @param {String} chars - Overrides the characters that should be removed from the string. It defaults to \r\n \t. +// @return {String} - The string without chars at the right-hand side. func RTrim(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 2) diff --git a/pkg/stdlib/strings/unescape.go b/pkg/stdlib/strings/unescape.go index a1a841ec..63c35283 100644 --- a/pkg/stdlib/strings/unescape.go +++ b/pkg/stdlib/strings/unescape.go @@ -8,13 +8,13 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values" ) -// UnescapeHTML unescapes entities like "<" to become "<". It unescapes a +// UNESCAPE_HTML unescapes entities like "<" to become "<". It unescapes a // larger range of entities than EscapeString escapes. For example, "á" // unescapes to "รก", as does "á" and "á". // UnescapeString(EscapeString(s)) == s always holds, but the converse isn't // always true. -// @param (String) - Uri to escape. -// @returns String - Escaped string. +// @param {String} uri - Uri to escape. +// @return {String} - Escaped string. func UnescapeHTML(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/testing/array.go b/pkg/stdlib/testing/array.go index bb7c17c2..4a151926 100644 --- a/pkg/stdlib/testing/array.go +++ b/pkg/stdlib/testing/array.go @@ -8,9 +8,9 @@ import ( "github.com/MontFerret/ferret/pkg/stdlib/testing/base" ) -// Array asserts that value is a array type. -// @params actual (Mixed) - Value to test. -// @params message (String, optional) - Message to display on error. +// ARRAY asserts that value is a array type. +// @param {Any} actual - Value to test. +// @param {String} [message] - Message to display on error. var Array = base.Assertion{ DefaultMessage: func(args []core.Value) string { return "be array" diff --git a/pkg/stdlib/testing/binary.go b/pkg/stdlib/testing/binary.go index af55241d..e13e7a8f 100644 --- a/pkg/stdlib/testing/binary.go +++ b/pkg/stdlib/testing/binary.go @@ -8,9 +8,9 @@ import ( "github.com/MontFerret/ferret/pkg/stdlib/testing/base" ) -// Binary asserts that value is a binary type. -// @params actual (Mixed) - Value to test. -// @params message (String, optional) - Message to display on error. +// BINARY asserts that value is a binary type. +// @param {Any} actual - Value to test. +// @param {String} [message] - Message to display on error. var Binary = base.Assertion{ DefaultMessage: func(args []core.Value) string { return "be binary" diff --git a/pkg/stdlib/testing/datetime.go b/pkg/stdlib/testing/datetime.go index 98d0f4ca..016c6243 100644 --- a/pkg/stdlib/testing/datetime.go +++ b/pkg/stdlib/testing/datetime.go @@ -8,9 +8,9 @@ import ( "github.com/MontFerret/ferret/pkg/stdlib/testing/base" ) -// DateTime asserts that value is a datetime type. -// @params actual (Mixed) - Value to test. -// @params message (String, optional) - Message to display on error. +// DATETIME asserts that value is a datetime type. +// @param {Any} actual - Value to test. +// @param {String} [message] - Message to display on error. var DateTime = base.Assertion{ DefaultMessage: func(args []core.Value) string { return "be datetime" diff --git a/pkg/stdlib/testing/empty.go b/pkg/stdlib/testing/empty.go index f912822a..2259868a 100644 --- a/pkg/stdlib/testing/empty.go +++ b/pkg/stdlib/testing/empty.go @@ -9,9 +9,9 @@ import ( "github.com/MontFerret/ferret/pkg/stdlib/testing/base" ) -// Empty asserts that the target does not contain any values. -// @params actual (Measurable|Binary|Object|Array|String) - Value to test. -// @params message (String, optional) - Message to display on error. +// EMPTY asserts that the target does not contain any values. +// @param {Measurable | Binary | Object | Any[] | String} actual - Value to test. +// @param {String} [message] - Message to display on error. var Empty = base.Assertion{ DefaultMessage: func(_ []core.Value) string { return "be empty" diff --git a/pkg/stdlib/testing/equal.go b/pkg/stdlib/testing/equal.go index 042b1e6e..6299aee4 100644 --- a/pkg/stdlib/testing/equal.go +++ b/pkg/stdlib/testing/equal.go @@ -8,10 +8,10 @@ import ( "github.com/MontFerret/ferret/pkg/stdlib/testing/base" ) -// Equal asserts equality of actual and expected values. -// @params actual (Mixed) - Actual value. -// @params expected (Mixed) - Expected value. -// @params message (String, optional) - Message to display on error. +// EQUAL asserts equality of actual and expected values. +// @param {Any} actual - Actual value. +// @param {Any} expected - Expected value. +// @param {String} [message] - Message to display on error. var Equal = base.Assertion{ DefaultMessage: func(args []core.Value) string { return fmt.Sprintf("be %s %s", base.EqualOp, base.FormatValue(args[1])) diff --git a/pkg/stdlib/testing/fail.go b/pkg/stdlib/testing/fail.go index 1d9c4b80..d92c9620 100644 --- a/pkg/stdlib/testing/fail.go +++ b/pkg/stdlib/testing/fail.go @@ -7,8 +7,8 @@ import ( "github.com/MontFerret/ferret/pkg/stdlib/testing/base" ) -// Fail returns an error. -// @params message (String, optional) - Message to display on error. +// FAIL returns an error. +// @param {String} [message] - Message to display on error. var Fail = base.Assertion{ DefaultMessage: func(_ []core.Value) string { return "not fail" diff --git a/pkg/stdlib/testing/false.go b/pkg/stdlib/testing/false.go index 25108992..cfd56705 100644 --- a/pkg/stdlib/testing/false.go +++ b/pkg/stdlib/testing/false.go @@ -9,9 +9,9 @@ import ( "github.com/MontFerret/ferret/pkg/stdlib/testing/base" ) -// False asserts that value is false. -// @params actual (Mixed) - Value to test. -// @params message (String) - Message to display on error. +// FALSE asserts that value is false. +// @param {Any}actual - Value to test. +// @param {String} [message] - Message to display on error. var False = base.Assertion{ DefaultMessage: func(args []core.Value) string { return fmt.Sprintf("be %s", base.FormatValue(values.False)) diff --git a/pkg/stdlib/testing/float.go b/pkg/stdlib/testing/float.go index 454e6bab..027148b3 100644 --- a/pkg/stdlib/testing/float.go +++ b/pkg/stdlib/testing/float.go @@ -8,9 +8,9 @@ import ( "github.com/MontFerret/ferret/pkg/stdlib/testing/base" ) -// Float asserts that value is a float type. -// @params actual (Mixed) - Value to test. -// @params message (String, optional) - Message to display on error. +// FLOAT asserts that value is a float type. +// @param {Any} actual - Value to test. +// @param {String} [message] - Message to display on error. var Float = base.Assertion{ DefaultMessage: func(args []core.Value) string { return "be float" diff --git a/pkg/stdlib/testing/gt.go b/pkg/stdlib/testing/gt.go index 5b5a712c..a6277727 100644 --- a/pkg/stdlib/testing/gt.go +++ b/pkg/stdlib/testing/gt.go @@ -8,10 +8,10 @@ import ( "github.com/MontFerret/ferret/pkg/stdlib/testing/base" ) -// Gt asserts that an actual value is greater than an expected one. -// @params actual (Mixed) - Actual value. -// @params expected (Mixed) - Expected value. -// @params message (String, optional) - Message to display on error. +// GT asserts that an actual value is greater than an expected one. +// @param {Any} actual - Actual value. +// @param {Any} expected - Expected value. +// @param {String} [message] - Message to display on error. var Gt = base.Assertion{ DefaultMessage: func(args []core.Value) string { return fmt.Sprintf("be %s %s", base.GreaterOp, base.FormatValue(args[1])) diff --git a/pkg/stdlib/testing/gte.go b/pkg/stdlib/testing/gte.go index 010d52d6..2110203b 100644 --- a/pkg/stdlib/testing/gte.go +++ b/pkg/stdlib/testing/gte.go @@ -8,10 +8,10 @@ import ( "github.com/MontFerret/ferret/pkg/stdlib/testing/base" ) -// Gte asserts that an actual value is greater than or equal to an expected one. -// @params actual (Mixed) - Actual value. -// @params expected (Mixed) - Expected value. -// @params message (String, optional) - Message to display on error. +// GTE asserts that an actual value is greater than or equal to an expected one. +// @param {Any} actual - Actual value. +// @param {Any} expected - Expected value. +// @param {String} [message] - Message to display on error. var Gte = base.Assertion{ DefaultMessage: func(args []core.Value) string { return fmt.Sprintf("be %s %s", base.GreaterOrEqualOp, base.FormatValue(args[1])) diff --git a/pkg/stdlib/testing/include.go b/pkg/stdlib/testing/include.go index ca55b0f3..8cec4e85 100644 --- a/pkg/stdlib/testing/include.go +++ b/pkg/stdlib/testing/include.go @@ -10,10 +10,10 @@ import ( "github.com/MontFerret/ferret/pkg/stdlib/testing/base" ) -// Include asserts that haystack includes needle. -// @params actual (String|Array|Object|Iterable) - Haystack value. -// @params expected (Mixed) - Expected value. -// @params message (String, optional) - Message to display on error. +// INCLUDE asserts that haystack includes needle. +// @param {String | Array | Object | Iterable} actual - Haystack value. +// @param {Any} expected - Expected value. +// @param {String} [message] - Message to display on error. var Include = base.Assertion{ DefaultMessage: func(args []core.Value) string { return fmt.Sprintf("include %s", base.FormatValue(args[1])) diff --git a/pkg/stdlib/testing/int.go b/pkg/stdlib/testing/int.go index f98d06e2..cc9f59f5 100644 --- a/pkg/stdlib/testing/int.go +++ b/pkg/stdlib/testing/int.go @@ -8,9 +8,9 @@ import ( "github.com/MontFerret/ferret/pkg/stdlib/testing/base" ) -// Int asserts that value is a int type. -// @params actual (Mixed) - Actual value. -// @params message (String, optional) - Message to display on error. +// INT asserts that value is a int type. +// @param {Any} actual - Actual value. +// @param {String} [message] - Message to display on error. var Int = base.Assertion{ DefaultMessage: func(args []core.Value) string { return "be int" diff --git a/pkg/stdlib/testing/len.go b/pkg/stdlib/testing/len.go index dd87aa75..0a1699d3 100644 --- a/pkg/stdlib/testing/len.go +++ b/pkg/stdlib/testing/len.go @@ -9,10 +9,10 @@ import ( "github.com/MontFerret/ferret/pkg/stdlib/testing/base" ) -// Len asserts that a measurable value has a length or size with the expected value. -// @params actual (Measurable) - Measurable value. -// @params length (Mixed) - Target length. -// @params message (String, optional) - Message to display on error. +// LEN asserts that a measurable value has a length or size with the expected value. +// @param {Measurable} actual - Measurable value. +// @param {Int} length - Target length. +// @param {String} [message] - Message to display on error. var Len = base.Assertion{ DefaultMessage: func(args []core.Value) string { return fmt.Sprintf("has size %s", args[1]) diff --git a/pkg/stdlib/testing/lib.go b/pkg/stdlib/testing/lib.go index d1e2df93..e385dab7 100644 --- a/pkg/stdlib/testing/lib.go +++ b/pkg/stdlib/testing/lib.go @@ -5,6 +5,7 @@ import ( "github.com/MontFerret/ferret/pkg/stdlib/testing/base" ) +// @namespace T func RegisterLib(ns core.Namespace) error { t := ns.Namespace("T") diff --git a/pkg/stdlib/testing/lt.go b/pkg/stdlib/testing/lt.go index 7563b483..f289ca5f 100644 --- a/pkg/stdlib/testing/lt.go +++ b/pkg/stdlib/testing/lt.go @@ -8,10 +8,10 @@ import ( "github.com/MontFerret/ferret/pkg/stdlib/testing/base" ) -// Lt asserts that an actual value is lesser than an expected one. -// @params actual (Mixed) - Actual value. -// @params expected (Mixed) - Expected value. -// @params message (String, optional) - Message to display on error. +// LT asserts that an actual value is lesser than an expected one. +// @param {Any} actual - Actual value. +// @param {Any} expected - Expected value. +// @param {String} [message] - Message to display on error. var Lt = base.Assertion{ DefaultMessage: func(args []core.Value) string { return fmt.Sprintf("be %s %s", base.LessOp, base.FormatValue(args[1])) diff --git a/pkg/stdlib/testing/lte.go b/pkg/stdlib/testing/lte.go index 93876b93..17d97a55 100644 --- a/pkg/stdlib/testing/lte.go +++ b/pkg/stdlib/testing/lte.go @@ -8,10 +8,10 @@ import ( "github.com/MontFerret/ferret/pkg/stdlib/testing/base" ) -// Lte asserts that an actual value is lesser than or equal to an expected one. -// @params actual (Mixed) - Actual value. -// @params expected (Mixed) - Expected value. -// @params message (String, optional) - Message to display on error. +// LTE asserts that an actual value is lesser than or equal to an expected one. +// @param {Any} actual - Actual value. +// @param {Any} expected - Expected value. +// @param {String} [message] - Message to display on error. var Lte = base.Assertion{ DefaultMessage: func(args []core.Value) string { return fmt.Sprintf("be %s %s", base.LessOrEqualOp, base.FormatValue(args[1])) diff --git a/pkg/stdlib/testing/match.go b/pkg/stdlib/testing/match.go index 2fea7a31..1433f74b 100644 --- a/pkg/stdlib/testing/match.go +++ b/pkg/stdlib/testing/match.go @@ -9,10 +9,10 @@ import ( "github.com/MontFerret/ferret/pkg/stdlib/testing/base" ) -// Match asserts that value matches the regular expression. -// @params actual (Mixed) - Actual value. -// @params expression (Mixed) - Regular expression. -// @params message (String, optional) - Message to display on error. +// MATCH asserts that value matches the regular expression. +// @param {Any} actual - Actual value. +// @param {String} expression - Regular expression. +// @param {String} [message] - Message to display on error. var Match = base.Assertion{ DefaultMessage: func(args []core.Value) string { return "match regular expression" diff --git a/pkg/stdlib/testing/none.go b/pkg/stdlib/testing/none.go index 1f40c699..1912f9ea 100644 --- a/pkg/stdlib/testing/none.go +++ b/pkg/stdlib/testing/none.go @@ -9,9 +9,9 @@ import ( "github.com/MontFerret/ferret/pkg/stdlib/testing/base" ) -// None asserts that value is none. -// @params actual (Mixed) - Value to test. -// @params message (String, optional) - Message to display on error. +// NONE asserts that value is none. +// @param {Any} actual - Value to test. +// @param {String} [message] - Message to display on error. var None = base.Assertion{ DefaultMessage: func(args []core.Value) string { return fmt.Sprintf("be %s", base.FormatValue(values.None)) diff --git a/pkg/stdlib/testing/object.go b/pkg/stdlib/testing/object.go index 2001ef13..8620969e 100644 --- a/pkg/stdlib/testing/object.go +++ b/pkg/stdlib/testing/object.go @@ -8,9 +8,9 @@ import ( "github.com/MontFerret/ferret/pkg/stdlib/testing/base" ) -// Object asserts that value is a object type. -// @params actual (Mixed) - Value to test. -// @params message (String, optional) - Message to display on error. +// OBJECT asserts that value is a object type. +// @param {Any} actual - Value to test. +// @param {String} [message] - Message to display on error. var Object = base.Assertion{ DefaultMessage: func(args []core.Value) string { return "be object" diff --git a/pkg/stdlib/testing/string.go b/pkg/stdlib/testing/string.go index 0442a38d..214e3a7b 100644 --- a/pkg/stdlib/testing/string.go +++ b/pkg/stdlib/testing/string.go @@ -8,9 +8,9 @@ import ( "github.com/MontFerret/ferret/pkg/stdlib/testing/base" ) -// String asserts that value is a string type. -// @params actual (Mixed) - Value to test. -// @params message (String, optional) - Message to display on error. +// STRING asserts that value is a string type. +// @param {Any} actual - Value to test. +// @param {String} [message] - Message to display on error. var String = base.Assertion{ DefaultMessage: func(args []core.Value) string { return "be string" diff --git a/pkg/stdlib/testing/true.go b/pkg/stdlib/testing/true.go index ab72dae2..a9225134 100644 --- a/pkg/stdlib/testing/true.go +++ b/pkg/stdlib/testing/true.go @@ -9,9 +9,9 @@ import ( "github.com/MontFerret/ferret/pkg/stdlib/testing/base" ) -// True asserts that value is true. -// @params actual (Mixed) - Value to test. -// @params message (String, optional) - Message to display on error. +// TRUE asserts that value is true. +// @param {Any} actual - Value to test. +// @param {String} [message] - Message to display on error. var True = base.Assertion{ DefaultMessage: func(args []core.Value) string { return fmt.Sprintf("be %s", base.FormatValue(values.True)) diff --git a/pkg/stdlib/types/is_array.go b/pkg/stdlib/types/is_array.go index 1ebd480c..4636236c 100644 --- a/pkg/stdlib/types/is_array.go +++ b/pkg/stdlib/types/is_array.go @@ -8,9 +8,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// IsArray checks whether value is an array value. -// @param value (Value) - Input value of arbitrary type. -// @returns (Boolean) - Returns true if value is array, otherwise false. +// IS_ARRAY checks whether value is an array value. +// @param {Any} value - Input value of arbitrary type. +// @return {Boolean} - Returns true if value is array, otherwise false. func IsArray(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/types/is_binary.go b/pkg/stdlib/types/is_binary.go index 05b63d69..354aa607 100644 --- a/pkg/stdlib/types/is_binary.go +++ b/pkg/stdlib/types/is_binary.go @@ -8,9 +8,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// IsBinary checks whether value is a binary value. -// @param value (Value) - Input value of arbitrary type. -// @returns (Boolean) - Returns true if value is binary, otherwise false. +// IS_BINARY checks whether value is a binary value. +// @param {Any} value - Input value of arbitrary type. +// @return {Boolean} - Returns true if value is binary, otherwise false. func IsBinary(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/types/is_boolean.go b/pkg/stdlib/types/is_boolean.go index d9cdede5..ddd640ff 100644 --- a/pkg/stdlib/types/is_boolean.go +++ b/pkg/stdlib/types/is_boolean.go @@ -8,9 +8,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// IsBool checks whether value is a boolean value. -// @param value (Value) - Input value of arbitrary type. -// @returns (Boolean) - Returns true if value is boolean, otherwise false. +// IS_BOOL checks whether value is a boolean value. +// @param {Any} value - Input value of arbitrary type. +// @return {Boolean} - Returns true if value is boolean, otherwise false. func IsBool(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/types/is_date_time.go b/pkg/stdlib/types/is_date_time.go index 87302c91..d0ee4a2c 100644 --- a/pkg/stdlib/types/is_date_time.go +++ b/pkg/stdlib/types/is_date_time.go @@ -8,9 +8,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// IsDateTime checks whether value is a date time value. -// @param value (Value) - Input value of arbitrary type. -// @returns (Boolean) - Returns true if value is date time, otherwise false. +// IS_DATETIME checks whether value is a date time value. +// @param {Any} value - Input value of arbitrary type. +// @return {Boolean} - Returns true if value is date time, otherwise false. func IsDateTime(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/types/is_float.go b/pkg/stdlib/types/is_float.go index e1d09977..df6997d9 100644 --- a/pkg/stdlib/types/is_float.go +++ b/pkg/stdlib/types/is_float.go @@ -8,9 +8,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// IsFloat checks whether value is a float value. -// @param value (Value) - Input value of arbitrary type. -// @returns (Boolean) - Returns true if value is float, otherwise false. +// IS_FLOAT checks whether value is a float value. +// @param {Any} value - Input value of arbitrary type. +// @return {Boolean} - Returns true if value is float, otherwise false. func IsFloat(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/types/is_html_document.go b/pkg/stdlib/types/is_html_document.go index ca0d9ed8..49eb5528 100644 --- a/pkg/stdlib/types/is_html_document.go +++ b/pkg/stdlib/types/is_html_document.go @@ -8,9 +8,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values" ) -// IsHTMLDocument checks whether value is a HTMLDocument value. -// @param value (Value) - Input value of arbitrary type. -// @returns (Boolean) - Returns true if value is HTMLDocument, otherwise false. +// IS_HTML_DOCUMENT checks whether value is a HTMLDocument value. +// @param {Any} value - Input value of arbitrary type. +// @return {Boolean} - Returns true if value is HTMLDocument, otherwise false. func IsHTMLDocument(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/types/is_html_element.go b/pkg/stdlib/types/is_html_element.go index 48bcfd28..ebff4c0b 100644 --- a/pkg/stdlib/types/is_html_element.go +++ b/pkg/stdlib/types/is_html_element.go @@ -8,9 +8,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values" ) -// IsHTMLElement checks whether value is a HTMLElement value. -// @param value (Value) - Input value of arbitrary type. -// @returns (Boolean) - Returns true if value is HTMLElement, otherwise false. +// IS_HTML_ELEMENT checks whether value is a HTMLElement value. +// @param {Any} value - Input value of arbitrary type. +// @return {Boolean} - Returns true if value is HTMLElement, otherwise false. func IsHTMLElement(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/types/is_int.go b/pkg/stdlib/types/is_int.go index 2d2265d1..a0148bef 100644 --- a/pkg/stdlib/types/is_int.go +++ b/pkg/stdlib/types/is_int.go @@ -8,9 +8,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// IsInt checks whether value is a int value. -// @param value (Value) - Input value of arbitrary type. -// @returns (Boolean) - Returns true if value is int, otherwise false. +// IS_INT checks whether value is a int value. +// @param {Any} value - Input value of arbitrary type. +// @return {Boolean} - Returns true if value is int, otherwise false. func IsInt(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/types/is_nan.go b/pkg/stdlib/types/is_nan.go index a7cf11f6..4e643c3b 100644 --- a/pkg/stdlib/types/is_nan.go +++ b/pkg/stdlib/types/is_nan.go @@ -8,9 +8,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// IsNaN checks whether value is NaN. -// @param value (Value) - Input value of arbitrary type. -// @returns (Boolean) - Returns true if value is NaN, otherwise false. +// IS_NAN checks whether value is NaN. +// @param {Any} value - Input value of arbitrary type. +// @return {Boolean} - Returns true if value is NaN, otherwise false. func IsNaN(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/types/is_none.go b/pkg/stdlib/types/is_none.go index 55062fbb..acd3d24a 100644 --- a/pkg/stdlib/types/is_none.go +++ b/pkg/stdlib/types/is_none.go @@ -8,9 +8,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// IsNone checks whether value is a none value. -// @param value (Value) - Input value of arbitrary type. -// @returns (Boolean) - Returns true if value is none, otherwise false. +// IS_NONE checks whether value is a none value. +// @param {Any} value - Input value of arbitrary type. +// @return {Boolean} - Returns true if value is none, otherwise false. func IsNone(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/types/is_object.go b/pkg/stdlib/types/is_object.go index fc96840e..64cc7364 100644 --- a/pkg/stdlib/types/is_object.go +++ b/pkg/stdlib/types/is_object.go @@ -8,9 +8,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// IsObject checks whether value is an object value. -// @param value (Value) - Input value of arbitrary type. -// @returns (Boolean) - Returns true if value is object, otherwise false. +// IS_OBJECT checks whether value is an object value. +// @param {Any} value - Input value of arbitrary type. +// @return {Boolean} - Returns true if value is object, otherwise false. func IsObject(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/types/is_string.go b/pkg/stdlib/types/is_string.go index 944d67b3..1a4666f4 100644 --- a/pkg/stdlib/types/is_string.go +++ b/pkg/stdlib/types/is_string.go @@ -8,9 +8,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values/types" ) -// IsString checks whether value is a string value. -// @param value (Value) - Input value of arbitrary type. -// @returns (Boolean) - Returns true if value is string, otherwise false. +// IS_STRING checks whether value is a string value. +// @param {Any} value - Input value of arbitrary type. +// @return {Boolean} - Returns true if value is string, otherwise false. func IsString(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/types/to_array.go b/pkg/stdlib/types/to_array.go index 14882bd4..a65cb7bb 100644 --- a/pkg/stdlib/types/to_array.go +++ b/pkg/stdlib/types/to_array.go @@ -6,13 +6,13 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values" ) -// toArray takes an input value of any type and convert it into an array value. -// @param (Value) - Input value of arbitrary type. -// @returns (Array) +// TO_ARRAY takes an input value of any type and convert it into an array value. // None is converted to an empty array // Boolean values, numbers and strings are converted to an array containing the original value as its single element // Arrays keep their original value // Objects / HTML nodes are converted to an array containing their attribute values as array elements. +// @param {Any} input - Input value of arbitrary type. +// @return {Any[]} - An array value. func ToArray(ctx context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/types/to_boolean.go b/pkg/stdlib/types/to_boolean.go index 9bb2392c..3510ae23 100644 --- a/pkg/stdlib/types/to_boolean.go +++ b/pkg/stdlib/types/to_boolean.go @@ -7,15 +7,15 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values" ) -// ToBool takes an input value of any type and converts it into the appropriate boolean value. -// @param value (Value) - Input value of arbitrary type. -// @returns (Boolean) - +// TO_BOOL takes an input value of any type and converts it into the appropriate boolean value. // None is converted to false // Numbers are converted to true, except for 0, which is converted to false // Strings are converted to true if they are non-empty, and to false otherwise // Dates are converted to true if they are not zero, and to false otherwise // Arrays are always converted to true (even if empty) // Objects / HtmlNodes / Binary are always converted to true +// @param {Any} value - Input value of arbitrary type. +// @return {Boolean} - The appropriate boolean value. func ToBool(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/types/to_date_time.go b/pkg/stdlib/types/to_date_time.go index fd31489d..2b82645f 100644 --- a/pkg/stdlib/types/to_date_time.go +++ b/pkg/stdlib/types/to_date_time.go @@ -7,9 +7,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values" ) -// ToDateTime takes an input value of any type and converts it into the appropriate date time value. -// @param value (Value) - Input value of arbitrary type. -// @returns (DateTime) - Parsed date time. +// TO_DATETIME takes an input value of any type and converts it into the appropriate date time value. +// @param {Any} value - Input value of arbitrary type. +// @return {DateTime} - Parsed date time. func ToDateTime(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/types/to_float.go b/pkg/stdlib/types/to_float.go index 0d4f9605..51579810 100644 --- a/pkg/stdlib/types/to_float.go +++ b/pkg/stdlib/types/to_float.go @@ -7,9 +7,7 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values" ) -// ToFloat takes an input value of any type and convert it into a float value. -// @param value (Value) - Input value of arbitrary type. -// @returns (Float) - +// TO_FLOAT takes an input value of any type and convert it into a float value. // None and false are converted to the value 0 // true is converted to 1 // Numbers keep their original value @@ -18,6 +16,8 @@ import ( // An empty array is converted to 0, an array with one member is converted into the result of TO_NUMBER() for its sole member. // An array with two or more members is converted to the number 0. // An object / HTML node is converted to the number 0. +// @param {Any} value - Input value of arbitrary type. +// @return {Float} - A float value. func ToFloat(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/types/to_int.go b/pkg/stdlib/types/to_int.go index ce54bd7f..e59b5b49 100644 --- a/pkg/stdlib/types/to_int.go +++ b/pkg/stdlib/types/to_int.go @@ -7,9 +7,7 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values" ) -// ToInt takes an input value of any type and convert it into an integer value. -// @param value (Value) - Input value of arbitrary type. -// @returns (Int) - +// TO_INT takes an input value of any type and convert it into an integer value. // None and false are converted to the value 0 // true is converted to 1 // Numbers keep their original value @@ -18,6 +16,8 @@ import ( // An empty array is converted to 0, an array with one member is converted into the result of TO_NUMBER() for its sole member. // An array with two or more members is converted to the number 0. // An object / HTML node is converted to the number 0. +// @param {Any} value - Input value of arbitrary type. +// @return {Int} - An integer value. func ToInt(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/types/to_string.go b/pkg/stdlib/types/to_string.go index 9d91acd8..128b93e2 100644 --- a/pkg/stdlib/types/to_string.go +++ b/pkg/stdlib/types/to_string.go @@ -7,9 +7,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values" ) -// ToString takes an input value of any type and convert it into a string value. -// @param value (Value) - Input value of arbitrary type. -// @return (String) - String representation of a given value. +// TO_STRING takes an input value of any type and convert it into a string value. +// @param {Any} value - Input value of arbitrary type. +// @return {String} - String representation of a given value. func ToString(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/types/type_name.go b/pkg/stdlib/types/type_name.go index 40aae45a..64585e58 100644 --- a/pkg/stdlib/types/type_name.go +++ b/pkg/stdlib/types/type_name.go @@ -7,9 +7,9 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values" ) -// TypeName returns the data type name of value. -// @param value (Value) - Input value of arbitrary type. -// @returns (Boolean) - Returns string representation of a type. +// TYPENAME returns the data type name of value. +// @param {Any} value - Input value of arbitrary type. +// @return {Boolean} - Returns string representation of a type. func TypeName(_ context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1) diff --git a/pkg/stdlib/utils/log.go b/pkg/stdlib/utils/log.go index 2440b31e..e2ed1d3c 100644 --- a/pkg/stdlib/utils/log.go +++ b/pkg/stdlib/utils/log.go @@ -8,7 +8,8 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values" ) -// Print writes messages into the system log. +// PRINT writes messages into the system log. +// @param {Value, repeated} message - Print message. func Print(ctx context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, core.MaxArgs) diff --git a/pkg/stdlib/utils/wait.go b/pkg/stdlib/utils/wait.go index b7c7d039..f8ee176e 100644 --- a/pkg/stdlib/utils/wait.go +++ b/pkg/stdlib/utils/wait.go @@ -8,8 +8,8 @@ import ( "github.com/MontFerret/ferret/pkg/runtime/values" ) -// Wait pauses the execution for a given period. -// @param timeout (Float|Int) - Number value which indicates for how long to stop an execution. +// WAIT pauses the execution for a given period. +// @param {Int | Float} timeout - Number value which indicates for how long to stop an execution. func Wait(ctx context.Context, args ...core.Value) (core.Value, error) { err := core.ValidateArgs(args, 1, 1)