From d2ad074a34323ae5518399e555b3c6e5c576295e Mon Sep 17 00:00:00 2001 From: Griffin Castles Date: Wed, 24 Jan 2024 19:37:11 +0800 Subject: [PATCH 1/5] =?UTF-8?q?=F0=9F=93=83=20docs(std):=20Add=20`must=5Fu?= =?UTF-8?q?se`?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Std documentation now has `must_use` functionality with the appropriate example --- docs/src/usage/std.md | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/docs/src/usage/std.md b/docs/src/usage/std.md index cc221491..4c6c3d9b 100644 --- a/docs/src/usage/std.md +++ b/docs/src/usage/std.md @@ -67,15 +67,22 @@ This field is used for allowing smarter introspection of how the argument given - "read" - This argument is only read from. Currently unused. - "write" - This argument is only written to. Used by `unused_variable` to assist in detecting a variable only being written to, even if passed into a function. +#### "must_use" +This field is used for checking if the return value of a function is used. + +- `true` - The default. The return value of this function must be used. +- `false` - The return value of this function does not need to be used. + Example: ```yml - table.insert: +table.find: args: - type: table - observes: write # This way, `table.insert(x, 1)` doesn't count as a read to `x` + observes: read # The table is only read from + required: true # The table to index is a required argument - type: any - - required: false - type: any + required: true # The value to find is a required argument + must_use: true # The return value of this function must be used ``` #### Argument types From b7c23500aa029dff2ea99af1d2c18af418bcd4de Mon Sep 17 00:00:00 2001 From: Griffin Castles Date: Thu, 25 Jan 2024 13:21:56 +0800 Subject: [PATCH 2/5] =?UTF-8?q?=F0=9F=93=83=20docs(std):=20Resolve=20defau?= =?UTF-8?q?lt?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `false` is now appropriately labelled as the default value of `must_use`. Resolves: https://github.com/Kampfkarren/selene/pull/583#discussion_r1465314527 --- docs/src/usage/std.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/src/usage/std.md b/docs/src/usage/std.md index 4c6c3d9b..61b1ed58 100644 --- a/docs/src/usage/std.md +++ b/docs/src/usage/std.md @@ -70,8 +70,8 @@ This field is used for allowing smarter introspection of how the argument given #### "must_use" This field is used for checking if the return value of a function is used. -- `true` - The default. The return value of this function must be used. -- `false` - The return value of this function does not need to be used. +- `true` - The return value of this function must be used. +- `false` - The default. The return value of this function does not need to be used. Example: ```yml From 607ca211d56b7850df50006631eceb5ebc9c87a6 Mon Sep 17 00:00:00 2001 From: Griffin Castles Date: Thu, 25 Jan 2024 13:59:27 +0800 Subject: [PATCH 3/5] =?UTF-8?q?=F0=9F=93=83=20docs(std):=20Resolve=20examp?= =?UTF-8?q?le?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `must_use` has its own example while `observes` and `required` have their respective example --- docs/src/usage/std.md | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/docs/src/usage/std.md b/docs/src/usage/std.md index 61b1ed58..bd36ac16 100644 --- a/docs/src/usage/std.md +++ b/docs/src/usage/std.md @@ -67,6 +67,17 @@ This field is used for allowing smarter introspection of how the argument given - "read" - This argument is only read from. Currently unused. - "write" - This argument is only written to. Used by `unused_variable` to assist in detecting a variable only being written to, even if passed into a function. +Example: +```yml + table.insert: + args: + - type: table + observes: write # This way, `table.insert(x, 1)` doesn't count as a read to `x` + - type: any + - required: false + type: any +``` + #### "must_use" This field is used for checking if the return value of a function is used. @@ -78,10 +89,10 @@ Example: table.find: args: - type: table - observes: read # The table is only read from - required: true # The table to index is a required argument + observes: read + required: true - type: any - required: true # The value to find is a required argument + required: true must_use: true # The return value of this function must be used ``` From 78b1523b8d906fbc608a977b9c17d6d03bc1d72e Mon Sep 17 00:00:00 2001 From: Griffin Castles Date: Fri, 26 Jan 2024 09:25:19 +0800 Subject: [PATCH 4/5] =?UTF-8?q?=F0=9F=93=83=20docs(std):=20Resolve=20hiera?= =?UTF-8?q?rchy?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The default option is now displayed correctly Resolves: https://github.com/Kampfkarren/selene/pull/583#discussion_r1466764865 --- docs/src/usage/std.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/usage/std.md b/docs/src/usage/std.md index bd36ac16..dda0ffd8 100644 --- a/docs/src/usage/std.md +++ b/docs/src/usage/std.md @@ -81,8 +81,8 @@ Example: #### "must_use" This field is used for checking if the return value of a function is used. -- `true` - The return value of this function must be used. - `false` - The default. The return value of this function does not need to be used. +- `true` - The return value of this function must be used. Example: ```yml From 9dd838a2143095670586564e7c15a5434578eff4 Mon Sep 17 00:00:00 2001 From: Griffin Castles Date: Fri, 26 Jan 2024 09:30:48 +0800 Subject: [PATCH 5/5] =?UTF-8?q?=F0=9F=93=83=20docs(std):=20Resolve=20`tost?= =?UTF-8?q?ring`?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replaced `table.find` example with a `tostring` example Resolves: https://github.com/Kampfkarren/selene/pull/583#discussion_r1466771313 --- docs/src/usage/std.md | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/docs/src/usage/std.md b/docs/src/usage/std.md index dda0ffd8..93e06247 100644 --- a/docs/src/usage/std.md +++ b/docs/src/usage/std.md @@ -86,14 +86,10 @@ This field is used for checking if the return value of a function is used. Example: ```yml -table.find: - args: - - type: table - observes: read - required: true - - type: any - required: true - must_use: true # The return value of this function must be used + tostring: + args: + - type: any + must_use: true ``` #### Argument types