Add GROUP to functions (#7622)

- Update list of groups to agreed list. - Lower case `ALIAS` names to be consistent with function names. - Add `GROUP` to methods. - All constructors and functions have doc comments. - Correct a few typos (e.g. `PRVIATE`). - Mark some more things as `PRIVATE`. - Use `ToDo:` and `Note:` consistently. - Order tags in doc comment. # Important Notes We don't have all the doc comments on types and will want to add them in future,
enso-org · Aug 23, 2023 · 7d83b3d · 7d83b3d
1 parent 4203a6e
commit 7d83b3d
Show file tree

Hide file tree

Showing 134 changed files with 1,952 additions and 1,114 deletions.
diff --git a/distribution/lib/Standard/AWS/0.0.0-dev/src/S3/S3.enso b/distribution/lib/Standard/AWS/0.0.0-dev/src/S3/S3.enso
@@ -7,7 +7,8 @@ import project.Internal.Auth
 polyglot java import software.amazon.awssdk.services.s3.model.S3Exception
 polyglot java import software.amazon.awssdk.services.s3.S3Client
 
-## Gets the list of the S3 bucket names.
+## GROUP Standard.Base.Input
+   Gets the list of the S3 bucket names.
 @credentials AWS_Credential.default_widget
 list_buckets : AWS_Credential | Nothing -> Vector Text ! S3_Error
 list_buckets credentials:(AWS_Credential | Nothing)=Nothing = handle_s3_errors <|

diff --git a/distribution/lib/Standard/Base/0.0.0-dev/package.yaml b/distribution/lib/Standard/Base/0.0.0-dev/package.yaml
@@ -10,35 +10,22 @@ maintainers:
     email: [email protected]
 component-groups:
   new:
-    - Input:
-        exports: []
-    - Web:
-        exports: []
-    - Parse:
-        exports:
-          - Standard.Base.Data.Json.Json.parse
-          - Standard.Base.Data.Text.Regex.compile
-          - Standard.Base.Data.Text.Regex.escape
-    - Select:
-        exports:
-          - Standard.Base.Data.Vector.Vector.at
-          - Standard.Base.Data.Vector.Vector.get
-          - Standard.Base.Data.Vector.Vector.filter
-          - Standard.Base.Data.Vector.Vector.find
-          - Standard.Base.Data.Vector.Vector.take
-          - Standard.Base.Data.Vector.Vector.drop
-          - Standard.Base.Data.Vector.Vector.partition
-          - Standard.Base.Data.Vector.Vector.distinct
-    - Join:
-        exports:
-          - Standard.Base.Data.Vector.Vector.zip
-    - Transform:
-        exports:
-          - Standard.Base.Data.Vector.Vector.insert
-          - Standard.Base.Data.Vector.Vector.remove
-          - Standard.Base.Data.Vector.Vector.map
-          - Standard.Base.Data.Vector.Vector.sort
-          - Standard.Base.Data.Vector.Vector.distinct
-    - Output:
-        exports:
-          - Standard.Base.Data.Text.Text.write
+    - Input: {}
+    - Constants: {}
+    - Metadata: {}
+    - Output: {}
+    - Calculations: {}
+    - Statistics: {}
+    - Selections: {}
+    - Conversions: {}
+    - Values: {}
+    - Math: {}
+    - Rounding: {}
+    - Trigonometry: {}
+    - Random: {}
+    - Bitwise: {}
+    - Text: {}
+    - DateTime: {}
+    - Logical: {}
+    - Operators: {}
+    - Errors: {}
diff --git a/distribution/lib/Standard/Base/0.0.0-dev/src/Any.enso b/distribution/lib/Standard/Base/0.0.0-dev/src/Any.enso
@@ -9,7 +9,6 @@ import project.Meta
 import project.Nothing.Nothing
 import project.Panic.Panic
 import project.Warning.Warning
-
 from project.Data.Boolean import Boolean, False, True
 from project.Data.Ordering import all
 from project.Data.Range.Extensions import all
@@ -21,7 +20,8 @@ from project.Function import const
    be used in that position.
 @Builtin_Type
 type Any
-    ## Generic conversion of an arbitrary Enso value to a corresponding textual
+    ## GROUP Conversions
+       Generic conversion of an arbitrary Enso value to a corresponding textual
        representation.
 
        > Example
@@ -52,7 +52,8 @@ type Any
     to_display_text : Text
     to_display_text self = @Builtin_Method "Any.to_display_text"
 
-    ## ALIAS Equals
+    ## ALIAS equals
+       GROUP Operators
        Checks if `self` is equal to `that`.
 
        Arguments:
@@ -99,7 +100,8 @@ type Any
     == : Any -> Boolean
     == self that = @Builtin_Method "Any.=="
 
-    ## ALIAS Not Equals
+    ## ALIAS not equals
+       GROUP Operators
        Checks if `self` is not equal to `that`.
 
        Arguments:
@@ -121,7 +123,8 @@ type Any
     != : Any -> Boolean
     != self that = (self == that).not
 
-    ## ALIAS Greater Than
+    ## ALIAS greater than
+       GROUP Operators
        Checks if `self` is greater than `that`.
 
        Arguments:
@@ -148,7 +151,8 @@ type Any
                 Nothing -> Error.throw (Incomparable_Values.Error self that)
                 _ -> False
 
-    ## ALIAS Greater Than or Equal
+    ## ALIAS greater than or equal
+       GROUP Operators
        Checks if `self` is greater than or equal to `that`.
 
        Arguments:
@@ -177,7 +181,8 @@ type Any
                 Nothing -> Error.throw (Incomparable_Values.Error self that)
                 _ -> False
 
-    ## ALIAS Less Than
+    ## ALIAS less than
+       GROUP Operators
        Checks if `self` is less than `that`.
 
        Arguments:
@@ -204,7 +209,8 @@ type Any
                 Nothing -> Error.throw (Incomparable_Values.Error self that)
                 _ -> False
 
-    ## ALIAS Less Than or Equal
+    ## ALIAS less than or equal
+       GROUP Operators
        Checks if `self` is less than or equal to `that`.
 
        Arguments:
@@ -235,7 +241,8 @@ type Any
                 Nothing -> Error.throw (Incomparable_Values.Error self that)
                 _ -> False
 
-    ## Checks if the type is an instance of `Nothing`.
+    ## GROUP Logical
+       Checks if the type is an instance of `Nothing`.
 
        Nothing in Enso is used as a universal value to indicate the lack of presence
        of a value. This function is primarily useful in the IDE.
@@ -247,7 +254,8 @@ type Any
     is_nothing : Boolean
     is_nothing self = False
 
-    ## If `self` is Nothing then returns `function`.
+    ## GROUP Logical
+       If `self` is Nothing then returns `function`.
 
        > Example
          If the value "Hello" is nothing return "".
@@ -257,7 +265,8 @@ type Any
     if_nothing self ~other =
         const self other
 
-    ## Executes the provided handler on an error, or returns the value unchanged.
+    ## GROUP Errors
+       Executes the provided handler on an error, or returns the value unchanged.
 
        Arguments:
        - error_type: The type of error to handle. Defaults to `Any` to handle
@@ -321,7 +330,8 @@ type Any
     map_error self ~f =
         const self f
 
-    ## Checks if `self` is an error.
+    ## GROUP Errors
+       Checks if `self` is an error.
 
        > Example
          Checking if the provided value is an error.
@@ -369,6 +379,7 @@ type Any
 
     ## PRIVATE
        ADVANCED
+       GROUP Operators
        Applies the function on the right hand side to the argument on the left.
 
        Arguments
@@ -390,7 +401,8 @@ type Any
     |> : (Any -> Any) -> Any
     |> self ~function = function self
 
-    ## Checks if any warnings (either all or of a specified type) are attached to the value.
+    ## GROUP Errors
+       Checks if any warnings (either all or of a specified type) are attached to the value.
 
        Arguments:
        - warning_type: The type to check if attached to the value. Defaults to any warning.
@@ -399,7 +411,8 @@ type Any
         _ = warning_type
         False
 
-    ## Remove the warnings (either all or of a specified type) attached to the value.
+    ## GROUP Errors
+       Remove the warnings (either all or of a specified type) attached to the value.
 
        Arguments:
        - warning_type: The type to remove if attached to the value. Defaults to all warnings.
@@ -408,7 +421,8 @@ type Any
         _ = warning_type
         self
 
-    ## Throws the first matching warning (either all or of a specified type) as a data flow error.
+    ## GROUP Errors
+       Throws the first matching warning (either all or of a specified type) as a data flow error.
 
        Arguments:
        - warning_type: The type to throw if attached to the value. Defaults to all warnings.

diff --git a/distribution/lib/Standard/Base/0.0.0-dev/src/Data.enso b/distribution/lib/Standard/Base/0.0.0-dev/src/Data.enso
@@ -19,7 +19,7 @@ import project.System.File.File
 from project.Data.Boolean import Boolean, False, True
 from project.System.File_Format import Auto_Detect, File_Format
 
-## ALIAS Load, Open
+## ALIAS load, open
    GROUP Input
    Reads a file into Enso.
    Uses the specified file format to parse the file into an Enso type. If not
@@ -60,9 +60,9 @@ read : Text | File -> File_Format -> Problem_Behavior -> Any ! File_Error
 read path format=Auto_Detect (on_problems=Problem_Behavior.Report_Warning) =
     File.new path . read format on_problems
 
-##  ALIAS Load Text, Open Text
-    GROUP Input
-    Open and read the file at the provided `path`.
+## ALIAS load text, open text
+   GROUP Input
+   Open and read the file at the provided `path`.
 
    Arguments:
    - path: The path of the file to open and read the contents of. It will
@@ -142,8 +142,8 @@ list_directory : (File | Text) -> Text -> Boolean -> Vector File
 list_directory directory name_filter=Nothing recursive=False =
     File.new directory . list name_filter=name_filter recursive=recursive
 
-## ALIAS Download, HTTP Get
-   GROUP Web
+## ALIAS download, http get
+   GROUP Input
    Fetches from the provided URI and returns the response, parsing the body if
    the content-type is recognised. Returns an  error if the status code does not
    represent a successful response.
@@ -169,7 +169,8 @@ fetch uri method=HTTP_Method.Get headers=[] try_auto_parse=True =
         if try_auto_parse.not then response else
             response.decode if_unsupported=response . catch handler=(_->response)
 
-## ALIAS Download, HTTP Get
+## ALIAS download, http get
+   GROUP Input
    Fetches from the URI and returns the response, parsing the body if the
    content-type is recognised. Returns an  error if the status code does not
    represent a successful response.