Merge pull request #516 from eliasp/typos-and-wording

Peefy · web-flow · commit e3d692d5939a · 2025-06-07T15:08:30.000+08:00
Clean-up for wording, typos, grammar, etc.
diff --git a/docs/community/release-policy/kcl.md b/docs/community/release-policy/kcl.md
@@ -30,4 +30,5 @@ The KCL project version release strategy is as follows:
 - Testing and Feedback: Before releasing the feature, allow some peers/users to try and test these new features through written documentation rather than oral descriptions. Receive feedback and make improvements.
 - Release and Announcements: Write Release Notes, PR articles, interpret scenarios and new features, and promote through various channels.
 
-> Note: All the above information is public and should be made available for all community developers to participate, discuss, and contribute.
+> **NOTE:**
+> All the above information is public and should be made available for all community developers to participate, discuss, and contribute.
diff --git a/docs/reference/lang/codelab/schema.md b/docs/reference/lang/codelab/schema.md
@@ -159,7 +159,7 @@ nginx = Deployment {
 
 ## 5. Write More Complex Logic in Schema
 
-Suppose we have some schema logic, we can wrapper it into schema:
+Suppose we have some schema logic, we can wrap it into a schema:
 
 ```python
 schema Deployment[priority]:
@@ -426,7 +426,7 @@ schema Volume:
     hostPath: str
 ```
 
-Since the attributes defined by the schema are **required** by default, the verification that judges that the variable cannot be None/Undefined can be omitted.
+Since the attributes defined by the schema are **required** by default, no check to ensure they are not `None`/`Undefined` is needed.
 
 ```python
 schema Volume:
@@ -474,7 +474,7 @@ Stderr:
 Schema check is failed to check condition: regex.match(image, "^[a-zA-Z]+:\d+\.\d+\.\d+$"), "image name should be like 'nginx:1.14.2'"
 ```
 
-> The verification capability of KCL covers the verification defined by Openapi so that we can write any API verifications through KCL.
+> The verification capability of KCL covers the verification defined by OpenAPI so that we can write any API verifications through KCL.
 
 ## 9. Create New Schema via Schema Inheritance
 
@@ -485,7 +485,7 @@ Usually, schema Deployment will be used in multiple scenarios. We can directly u
 For example, we can use the Deployment schema as a basis, to define the nginx's base schema, and extend the definition
 in each scenario.
 
-In this case, we define some commonly used attributes. Please note that we mark the name to be immutable with the 'final' keyword to prevent it from being overwritten.
+In this case, we define some commonly used attributes. Please note that to prevent the attribut `name` from being overwritten as immutable by assigning its final value.
 
 ```python
 schema Nginx(Deployment):
@@ -604,7 +604,8 @@ mixin PersistentVolumeClaimMixin for PVCProtocol:
         }
 ```
 
-> Note: for the `k8s.api.core.v1` import to work, we need to initialize a module and add the `k8s` module as a dependency:
+> **NOTE:**
+> For the `k8s.api.core.v1` import to work, we need to initialize a module and add the `k8s` module as a dependency:
 >
 > ```bash
 > kcl mod init
diff --git a/docs/reference/lang/codelab/simple.md b/docs/reference/lang/codelab/simple.md
@@ -108,8 +108,8 @@ image: nginx:1.14.2
 service: my-service
 ```
 
-.. note::
-KCL has rich support of operators and string member functions, please read manual and specification for more details.
+> **NOTE:**
+> KCL has rich support of operators and string member functions, please read the manual and specification for more details.
 
 ## 4. Write Collections
 
@@ -183,8 +183,8 @@ else:
 cpu = _cpu
 memory = _cpu * 2
 _command = ["nginx"] # a list
-_command = _command + ["-f", "file"]  # Append items into command using + operator to contact two lists
-command = [c.lower() for c in _command]  # Take each element in the list to lowercase
+_command = _command + ["-f", "file"]  # Append items into command using + operator to concatenate two lists
+command = [c.lower() for c in _command]  # Convert each element in the list to lowercase
 _labels = {
     run = "my-nginx"
     if _env:
diff --git a/docs/reference/lang/spec/kcl-spec.md b/docs/reference/lang/spec/kcl-spec.md
@@ -10,9 +10,9 @@ description: KCL Spec
 
 ### Keywords and reserved words
 
-The following are the keywords of the KCL:
+The following identifiers are used as reserved words, or keywords of the language, and cannot be used as ordinary identifiers. They must be spelled exactly as written here:
 
-```python
+```
 True       False      None        Undefined   import
 and        or         in          is          not
 as         if         else        elif        for
@@ -21,9 +21,9 @@ all        any        map         filter      lambda
 rule
 ```
 
-The following are reserved words for the KCL:
+The following tokens are not used, but they are reserved as possible future keywords:
 
-```python
+```
 pass       return     validate   rule        flow
 def        del        raise      except      try
 finally    while      from       with        yield
@@ -32,13 +32,13 @@ global     nonlocal   struct     class       final
 
 ### Line comment
 
-```python
+```
 # a comment
 ```
 
 ### Operators
 
-```python
+```
 +       -       *       **      /       //      %
 <<      >>      &       |       ^       <       >
 ~       <=      >=      ==      !=      =
@@ -48,7 +48,7 @@ global     nonlocal   struct     class       final
 
 ### Delimiters
 
-```python
+```
 (       )       [       ]       {       }
 ,       :       .       ;       @
 ```
@@ -76,7 +76,7 @@ The following list of operators is ordered from **highest to lowest**:
 
 ## Grammar
 
-KCL uses Python's [LarkParser](https://lark-parser.readthedocs.io/en/latest/) tool to describe the grammar, and the specification rules are as follows:
+KCL uses the Python-based [LarkParser](https://lark-parser.readthedocs.io/en/latest/) tool to describe the grammar, and the specification rules are as follows:
 
 ```bnf
 //////////// KCL grammar ////////////
diff --git a/docs/reference/lang/spec/lexical.md b/docs/reference/lang/spec/lexical.md
@@ -56,8 +56,7 @@ A physical line is a sequence of characters end with a line termination sequence
 
 To join multiple physical lines into one logical line, the `\` character can be used. The character should be the last none-space character in each physical line except the very last line.
 
-> **note**
->
+> **NOTE:**
 > Any character except the ASCII space, tab (`\t`) and formfeed (`\f`) is considered a none-space character.
 
 - A line ending in a backslash cannot carry a comment (, which will be introduced shortly afterwards).
diff --git a/docs/reference/lang/spec/schema.md b/docs/reference/lang/spec/schema.md
@@ -527,7 +527,7 @@ The result is a **dict**:
 {
     'person': {
         'name': {
-            'firstName': 'Jhon',
+            'firstName': 'John',
             'lastName': 'Doe'
         }
     }
@@ -640,7 +640,7 @@ The result is a **dict**:
     'JohnDoe': {
         'firstName': 'John'
         'lastName': 'Doe'
-        'fullName': 'John Doe'
+        'fullName': 'John_Doe'
         'subject': 'CS'
     }
 }
diff --git a/docs/reference/lang/spec/variables.md b/docs/reference/lang/spec/variables.md
@@ -36,7 +36,7 @@ spam = "ham"
 spam = "eggs" # Error: The immutability rule is violated!
 ```
 
-- A variable starts with the `_` character is mutable.
+- A variable starting with the `_` character is mutable.
 
 ```python
 _spam
diff --git a/docs/reference/xlang-api/wasm-api.md b/docs/reference/xlang-api/wasm-api.md
@@ -18,7 +18,8 @@ Install the dependency
 npm install buffer @wasmer/wasi @kcl-lang/wasm-lib
 ```
 
-> Note: buffer is required by @wasmer/wasi.
+> **NOTE:**
+> Buffer is required by @wasmer/wasi.
 
 Write the code
 
@@ -43,7 +44,8 @@ main();
 
 Here, we use `webpack` to bundle the website, the `webpack.config.js` config as follows.
 
-> Note: This configuration includes necessary settings for @wasmer/wasi and other required plugins.
+> **NOTE:**:
+> This configuration includes necessary settings for @wasmer/wasi and other required plugins.
 
 ```js
 const HtmlWebpackPlugin = require("html-webpack-plugin");
diff --git a/docs/user_docs/concepts/package-and-module.md b/docs/user_docs/concepts/package-and-module.md
@@ -10,7 +10,8 @@ Within a **module**, KCL organizes files grouped by **package**. A package can b
 
 A KCL module contains a configuration laid out in a directory hierarchy. It contains everything that is needed to deterministically determine the outcome of a KCL configuration. The root of this directory is marked by containing a `kcl.mod` directory. The contents of this directory are mostly managed by the kcl tool such as `kpm`, etc. In that sense, `kcl.mod` is analogous to the `.git` directory marking the root directory of a repo, but where its contents are mostly managed by the git tool. Besides, a KCL module is the largest unit of the file organization, has a fixed location of all KCL files and dependencies.
 
-> Note: The use of a KCL module e.g., `kcl.mod` is optional, but required if one wants to manage, distribute, share and reuse code with a semantic version.
+> **NOTE:**
+> The use of a KCL module e.g., `kcl.mod` is optional, but required if one wants to manage, distribute, share and reuse code with a semantic version.
 
 ### Creating a module
 
@@ -140,7 +141,8 @@ kcl_cli_configs:
 kcl -Y kcl.yaml
 ```
 
-> Note: If we do not specify any input files for KCL, KCL will find the default `kcl.yaml` from the command line execution path to read the input file. Besides, if we tell KCL both the input files and the compilation setting file, KCL will take input files entered by the user as the final value.
+> **NOTE:**
+> If we do not specify any input files for KCL, KCL will find the default `kcl.yaml` from the command line execution path to read the input file. Besides, if we tell KCL both the input files and the compilation setting file, KCL will take input files entered by the user as the final value.
 
 ```bash
 # Whether the 'files' field is configured in `kcl.yaml` or not, the final value of input files is ["file1.k", "file2.k"]
diff --git a/docs/user_docs/guides/ci-integration/1-github-actions.md b/docs/user_docs/guides/ci-integration/1-github-actions.md
@@ -9,7 +9,8 @@ sidebar_label: Github Actions
 
 In the GitOps section, we have introduced how to integrate KCL with GitOps. In this section, we will continue to provide sample solutions for KCL and CI integrations. We hope to implement the end-to-end application development process by using containers, Continuous Integration (CI) for generation, and GitOps for Continuous Deployment (CD). In this scheme, we use a **Flask application** and **Github Actions** as examples.
 
-> Note: You can use any containerized application and different CI systems such as **Gitlab CI**, **Jenkins CI**, etc. in this solution.
+> **NOTE:**
+> You can use any containerized application and different CI systems such as **Gitlab CI**, **Jenkins CI**, etc. in this solution.
 
 The overall workflow is as follows:
 
diff --git a/docs/user_docs/guides/ci-integration/2-gitlab-ci.md b/docs/user_docs/guides/ci-integration/2-gitlab-ci.md
@@ -9,7 +9,8 @@ sidebar_label: Gitlab CI
 
 In the GitOps section, we have introduced how to integrate KCL with GitOps. In this section, we will continue to provide sample solutions for KCL and CI integrations. We hope to implement the end-to-end application development process by using containers, Continuous Integration (CI) for generation, and GitOps for Continuous Deployment (CD). In this scheme, we use a **Flask application** and **Gitlab CI** as examples.
 
-> Note: You can use any containerized application and different CI systems such as **Github Actions**, **Jenkins CI**, etc. in this solution.
+> **NOTE:**
+> You can use any containerized application and different CI systems such as **Github Actions**, **Jenkins CI**, etc. in this solution.
 
 The overall workflow is as follows:
 
diff --git a/docs/user_docs/support/faq-kcl.md b/docs/user_docs/support/faq-kcl.md
@@ -73,7 +73,8 @@ bob = Person {
 }
 ```
 
-> Note: All KCL variables can be assigned the null value `None` and the undefined value `Undefined`.
+> **NOTE:**
+> All KCL variables can be assigned the null value `None` and the undefined value `Undefined`.
 
 ## 3. What do some KCL variable names prefixed with `_` underscore mean? What's the difference between without the `_` underscore prefix? In what scenarios are they suitable for use?
 
@@ -172,7 +173,8 @@ _args = [*_args, "end"]  # Add elements "end" to the end of the list: ["a", "b",
 _args = ["start", *_args]  # Add elements "start" to the head of the list: ["start", "a", "b", "x", "c", "end"]
 ```
 
-> Note: When the consecutive variables are `None/Undefined`, using `+` may cause an error, then we can use the list unpacking operator `*` or use the `or` operator to take the default value of the list to avoid null values judge.
+> **NOTE:**
+> When the consecutive variables are `None/Undefined`, using `+` may cause an error, then we can use the list unpacking operator `*` or use the `or` operator to take the default value of the list to avoid null values judge.
 
 ```python
 data1 = [1, 2, 3]
@@ -383,7 +385,8 @@ success = True
 _result = "success" if success else "failed"
 ```
 
-> Note: When writing an if-elif-else block statement, pay attention to the colon `:` after the if condition and keep the indentation consistent.
+> **NOTE:**
+> When writing an if-elif-else block statement, pay attention to the colon `:` after the if condition and keep the indentation consistent.
 
 In addition, conditional expressions can also be written directly in a list or dict (the difference is that the value to be written in the if expression written in the structure is not a statement):
 
@@ -964,7 +967,8 @@ employee:
   nationality: China
 ```
 
-> Note: KCL only allows schema single inheritance.
+> **NOTE:**
+> KCL only allows schema single inheritance.
 
 ## 24. How to reuse schema logic through composition?
 
@@ -1037,7 +1041,8 @@ import ..service  # Relative path import, parent directory
 import ...root  # Relative path import, parent directory of parent directory
 ```
 
-> Note that for KCL's entry file `main.k`, it cannot import the folder where it is located, otherwise a circular import error will occur:
+> **NOTE:**
+> For KCL's entry file `main.k`, it cannot import the folder where it is located, otherwise a circular import error will occur:
 
 ```python
 import model  # Error: recursively loading
@@ -1122,7 +1127,8 @@ The continue second line\
 """
 ```
 
-Note: Use the line continuation character `\` while maintaining indentation, as follows:
+> **NOTE:**
+> Use the line continuation character `\` while maintaining indentation, as follows:
 
 - Error use case:
 
@@ -1192,7 +1198,8 @@ theFirstItem = data[0]  # Get the element with index 0 in the list, that is, the
 theSecondItem = data[1]  # Get the element with index 1 in the list, which is the first element 2
 ```
 
-> Note: The value of the index cannot exceed the length of the list, otherwise an error will occur, we can use the `len` function to get the length of the list.
+> **NOTE:**
+> The value of the index cannot exceed the length of the list, otherwise an error will occur, we can use the `len` function to get the length of the list.
 
 ```python
 data = [1, 2, 3]
@@ -1271,7 +1278,8 @@ data2 = data["contains.dot"]  # "value3"
 # Note that this is wrong: data3 = data.contains.dot
 ```
 
-> Note: The above sub-element operators cannot operate on values of non-list/dict/schema collection types, such as integers, nulls, etc.
+> **NOTE:**
+> The above sub-element operators cannot operate on values of non-list/dict/schema collection types, such as integers, nulls, etc.
 
 ```python
 data = 1
@@ -1363,7 +1371,8 @@ if: 1
 else: s
 ```
 
-> Note: Prefixing non-keyword identifiers with `$` has the same effect as not adding.
+> **NOTE:**
+> Prefixing non-keyword identifiers with `$` has the same effect as not adding.
 
 ```python
 _a = 1
@@ -1386,7 +1395,8 @@ int: 1
 str: 2
 ```
 
-> Note: If there are no special requirements, it is not recommended that the names of variables take these built-in types, because in some languages, they exist as keywords.
+> **NOTE:**
+> If there are no special requirements, it is not recommended that the names of variables take these built-in types, because in some languages, they exist as keywords.
 
 ## 33. How to implement enumeration in KCL?
 
@@ -1564,7 +1574,8 @@ data = { # The merged writing order of the same attribute labels does not affect
 } # The final data value is {"labels": {"key1": "value1", "key2": "value2"}}
 ```
 
-Note: The merge attribute operator will check the merged values ​​for conflicts, and report an error when the configuration values ​​that need to be merged conflict.
+> **NOTE:**
+> The merge attribute operator will check the merged values for conflicts and report an error when the configuration values that need to be merged conflict.
 
 ```python
 data = {
diff --git a/docs/user_docs/support/faq-yaml.md b/docs/user_docs/support/faq-yaml.md
@@ -17,7 +17,8 @@ string2: 'here''s to "quotes"'
 string3: here's to "quotes"
 ```
 
-> Note: KCL's strategy for outputting YAML strings is to output unquoted strings or double-quoted strings preferentially when single quotes appear in the string content, and output single-quoted strings in other cases to avoid the burden of understanding.
+> **NOTE:**
+> KCL's strategy for outputting YAML strings is to output unquoted strings or double-quoted strings preferentially when single quotes appear in the string content, and output single-quoted strings in other cases to avoid the burden of understanding.
 
 For more details, please refer to [YAML Spec v1.2](https://yaml.org/spec/1.2.1/)
 

Original file line number	Diff line number	Diff line change
`@@ -527,7 +527,7 @@ The result is a dict:`
`527`	`527`	`{`
`528`	`528`	`'person': {`
`529`	`529`	`'name': {`
`530`		`- 'firstName': 'Jhon',`
	`530`	`+ 'firstName': 'John',`
`531`	`531`	`'lastName': 'Doe'`
`532`	`532`	`}`
`533`	`533`	`}`
`@@ -640,7 +640,7 @@ The result is a dict:`
`640`	`640`	`'JohnDoe': {`
`641`	`641`	`'firstName': 'John'`
`642`	`642`	`'lastName': 'Doe'`
`643`		`- 'fullName': 'John Doe'`
	`643`	`+ 'fullName': 'John_Doe'`
`644`	`644`	`'subject': 'CS'`
`645`	`645`	`}`
`646`	`646`	`}`