doc: add more info about attributes

Author: Yoorkin

next/language/attributes.md

@@ -0,0 +1,269 @@
+# Attribute
+
+Attributes are annotations placed before structures in source code. They take the form `#attribute(...)`.
+An attribute occupies the entire line, and newlines are not allowed within it. 
+Attributes do not normally affect the meaning of programs. Unused attributes will be reported as warnings.
+
+The syntax of attributes is defined as follows:
+
+```
+attribute ::= '#' attribute-name
+            | '#' attribute-name '(' properties ')' 
+
+attribute-name ::= LIDENT | LIDENT '.' LIDENT
+
+properties ::= property (',' property)*
+
+property ::= expr | LIDENT '=' expr 
+
+expr ::= LIDENT | UIDENT | STRING | 'true' | 'false'
+       | LIDENT '.' LIDENT
+       | LIDENT '(' properties ')'
+       | LIDENT '.' LIDENT '(' properties ')'
+```
+
+The attributes has two forms: the built-in attributes and user-defined attributes.
+Built-in attributes are recognized by the MoonBit compiler and have specific meanings.
+User-defined attributes are ignored by the compiler, but can be used by external tools,
+via parsing the source code. 
+
+```{note}
+MoonBit is designed not to support runtime reflection. It's easy to abuse, making it impossible for toolchains (e.g., the compiler) to catch errors at compile time, which makes code harder to maintain. It also negatively impacts performance optimization. 
+
+We perfer to use compile-time code generation, keeping the benefits of static typing and performance (should also be used judiciously to avoid unnecessary complexity).  
+```
+
+## Deprecated Attribute
+
+The `#deprecated` attribute is used to mark an API as deprecated. MoonBit emits 
+a warning when the deprecated API is used, and if the API is listed in completion, 
+it will be shown with a strikethrough style. For example:
+
+```{literalinclude} /sources/language/src/attributes/top.mbt
+:language: moonbit
+:start-after: start deprecated
+:end-before: end deprecated
+```
+
+The `#deprecated` attribute can be used in the following contexts:
+
+- Top-level value declarations (including `fn`, `let`, and `const`)
+- Top-level type declarations (including `type`, `struct`, and `enum`)
+- Trait method declarations
+- Trait default implementations
+
+It has three forms:
+
+- `#deprecated`
+
+  Marks the item as deprecated with a default warning message.
+
+- `#deprecated("Use new_function instead")`
+
+  Marks the item as deprecated with a custom warning message. Every time the deprecated API is used, the provided message will be displayed as a warning.
+
+- `#deprecated("Use new_function instead", skip_current_package=true)`
+
+  Marks the item as deprecated with a custom warning message, but skips emitting warnings when the deprecated API is used within the same package.
+
+## Alias Attribute
+
+The `alias` attribute is used to overload operators related to indexing, or to create an alias name for a top-level function or variable. It has two forms:
+
+  
+- `#alias("op")`: where `op` is one of the following strings representing the indexing operators:
+
+  - `_[_]`: for the indexing operator
+  - `_[_]=_` for the indexing assignment operator 
+  - `_[_:_]` for the as view operator
+
+- `#alias(id)`: where `id` is a identifier representing the alias name.
+
+Both forms allowed additional properties:
+
+- `visibility="modifier"` 
+
+  A labeled property, changes the visibility of the alias. The `modifier` can be `pub` or `priv`. If not specified, the alias will have the same visibility as the original function or variable.
+
+- `deprecated` or `deprecated="message"`
+
+  Marks the alias as deprecated. If a message is provided, it will be displayed as a warning when the alias is used.
+
+To graceful migration from old API to new API, you can rename the old API directly, and create an alias with the old name, mark it as deprecated. For 
+example:
+
+```{code-block} moonbit
+:class: top-level
+#alias("old_name", deprecated)
+fn new_name() -> Unit {
+  ...
+}
+```
+
+## `label_migration` Attribute
+
+The `#label_migration` attribute is used to help you safely evolve your API 
+by warning users during the transition period. 
+
+It has three following forms:
+
+- `#label_migration(id, fill=true, msg="message")`
+
+  The `fill` property is used when you want to refactor an optional parameter.
+You can use `fill=true` when you want to eventually make an optional 
+parameter required. You can use `fill=false` when you want to eventually 
+remove an optional parameter.
+  
+  The `msg` property is an string that provides additional information about the migration.
+
+  ```{code-block} moonbit
+  :class: top-level
+  #label_migration(x, fill=true)
+  #label_migration(y, fill=false)
+  fn f(x~: Int = 0, y~: Int = 1) -> Unit { ... }
+  fn main {
+    f(x=1, y=1) // warn on y being filled
+    f()         // warn on x not being filled
+  }
+  ```
+
+- `#label_migration(id, allow_positional=true, msg="message")`
+
+  The `allow_positional` property is used when you want a labelled parameter to be 
+used without its label being provided. When the parameter is used positionally 
+(without a label), the compiler reports a warning. This is useful when you want to change a positional parameter
+to a labelled parameter without breaking the downstream code.
+
+  The `msg` property is an string that provides additional information about the migration.
+
+  ```{code-block} moonbit
+  :class: top-level
+  #label_migration(x, allow_positional=true)
+  fn f(x~: Int) -> Unit { ... }
+
+  fn main {
+    f(42) // warn on positional argument 42 used without label
+  }
+  ```
+
+- `#label_migration(id, alias=new_id, msg="message")`
+
+  The alias property allows you to provide an alternative name to a labelled
+parameter. This is useful when renaming a parameter to maintain backward 
+compatibility. If a warning message is provided, the compiler warns when 
+using the alias; otherwise, the alias can be used without warnings.
+
+  The `msg` property is an string that provides additional information about the migration.
+
+  ```{code-block} moonbit
+  :class: top-level
+  #label_migration(x, alias=xx)
+  #label_migration(x, alias=y, msg="warning")
+  fn f(x~: Int) -> Unit { ... }
+
+  fn main {
+    f(xx=42) // no warning
+    f(y=42)  // warning
+  }
+  ```
+
+## Visibility Attribute
+
+```{note}
+This topic does not covered the access control. To lean more about `pub`, `pub(all)` and `priv`, see [Access Control](./packages.md#access-control).
+```
+
+The `#visibility` attribute is similar to the `#deprecated` attribute, but it is used to hint that a type will change its visibility in the future. 
+For outside usages, if the usage will be invalidated by the visibility change in future, a warning will be emitted. 
+
+```{literalinclude} /sources/language/src/attributes/top.mbt
+:language: moonbit
+:start-after: start visibility
+:end-before: end visibility
+```
+
+The `#visibility` attribute takes two arguments: `change_to` and `message`.
+
+- The `change_to` argument is a string that indicates the new visibility of the type. It can be either `"abstract"` or `"readonly"`.
+
+  | `change_to` | Invalidated Usages |
+  |-------------|--------------------|
+  | `"readonly"`  | Creating an instance of the type or mutating the fields of the instance. |
+  | `"abstract"`  | Creating an instance of the type, mutating the fields of the instance, pattern matching, or accessing fields by label. |
+
+- The `message` argument is a string that provides additional information about the visibility change.
+
+## Internal Attribute
+
+The `#internal` attribute is used to mark a function, type, or trait as internal. 
+Any usage of the internal function or type in other modules will emit an alert warning.
+
+```{code-block} moonbit
+:class: top-level
+#internal(unsafe, "This is an unsafe function")
+fn unsafe_get[A](arr : Array[A]) -> A {
+  ...
+}
+```
+
+The internal attribute takes two arguments: `category` and `message`. 
+`category` is a identifier that indicates the category of the alert, and `message` is a string that provides additional message for the alert.
+
+The alert warnings can be turn off by setting the `warn-list` in `moon.pkg.json`.
+For more detail, see [Alert](../toolchain/moon/package.md#alert-list).
+
+## External Attribute
+
+The `#external` attribute is used to mark an abstract type as external type.
+
+- For Wasm(GC) backends, it would be interpreted as `anyref`.
+- For JavaScript backend, it would be interpreted as `any`.
+- For native backends, it would be interpreted as `void*`.
+
+```{code-block} moonbit
+:class: top-level
+#external
+type Ptr
+```
+
+## Borrow and Owned Attribute
+
+The `#borrow` and `#owned` attribute is used to indicate that a FFI takes ownership of its arguments. For more detail, see [FFI](./ffi.md#the-borrow-attribute).
+
+## `as_free_fn` Attribute
+
+The `#as_free_fn` attribute is used to mark a method that it is declared as a free function as well.
+It can also change the visibility of the free function, the name of the free function, and provide separate deprecation warning.
+
+```{literalinclude} /sources/language/src/misc/top.mbt
+:language: moonbit
+:start-after: start as_free_fn 1
+:end-before: end as_free_fn 1
+```
+
+## Callsite Attribute
+
+The `#callsite` attribute is used to mark properties that happen at callsite.
+
+It could be `autofill`, which is to autofill the arguments [SourceLoc and ArgLoc](/language/fundamentals.md#autofill-arguments)
+at callsite.
+
+
+## Skip Attribute
+
+The `#skip` attribute is used to skip a single test block. The type checking will still be performed.
+
+## Configuration attribute
+
+The `#cfg` attribute is used to perform conditional compilation. Examples are:
+
+<!-- MANUAL CHECK -->
+
+```moonbit
+#cfg(true)
+#cfg(false)
+#cfg(target="wasm")
+#cfg(not(target="wasm"))
+#cfg(all(target="wasm", true))
+#cfg(any(target="wasm", target="native"))
+```