Update

Author: topframe

_pages/en/docs/guides/introduce-apon.md

@@ -29,30 +29,57 @@ APON is a data format that combines features from both JSON and YAML to enhance
 | **Item Separation** | Comma (`,`) | Newline + Indentation | **Newline** |
 | **Comments** | Not supported | Supported (`#`) | Supported (`#`) |
 
-The biggest differences are in **how the structure is defined** and **how items are separated**. APON creates an explicit structure with parentheses like JSON, but uses newlines as item separators to maximize readability. This is a distinct feature from YAML, which defines the entire structure through the combination of newlines and indentation.
+The biggest differences are in **how the structure is defined** and **how items are separated**. APON creates an explicit structure with parentheses like JSON, but uses newlines as item separators to maximize readability. This is a distinct feature from YAML, which defines the entire structure through the combination of newlines and indentation. Also, by not using commas (`,`), APON prevents syntax errors common in JSON (like trailing comma issues) when adding or removing items, and keeps change history in version control systems (like Git) clean.
 
 ## 2. Basic Syntax
 
+### Comments
+
+In APON, comments must start with the `#` character on a **new line**.
+**Inline comments** (adding a comment after a parameter value on the same line) are **not supported**.
+
+This design choice avoids forcing the use of quotes when the `#` character is part of the data value (e.g., CSS color codes like `#FFFFFF` or hashtags), thereby increasing input flexibility.
+
+```apon
+# Correct usage of comments
+timeout: 30
+
+# Incorrect usage (treated as a string value, not a comment)
+# The value of timeout becomes the string "30 # 30 seconds", not the number 30.
+timeout: 30 # 30 seconds
+```
+
 ### Single Value (Parameter)
 
 The most basic unit in APON can have a single value in the format `name: value`.
+Keys and values are separated by a colon (`:`), and the value extends from the colon to the **end of the line**.
+
+This characteristic offers several advantages:
+*   Quotes are not required even if the value contains spaces in the middle.
+*   Values containing special characters, like URLs or file paths, can be written as-is without escaping.
+*   There is no need to type a comma (`,`) to indicate the end of a value.
+
 It is common to omit quotes (`"`) unless the value has the following special conditions:
 
-*   If there are spaces at the beginning or end of the value.
+*   If there are spaces at the beginning or end of the value (spaces in the middle are fine).
 *   If the value contains single (`'`) or double (`"`) quotes.
 *   If the value contains a newline character (`\n`).
+*   If the value is an empty string.
 
 ```apon
-# Example without double quotes
+# Example without double quotes (Value extends to the end of the line)
 name: John Doe
 age: 30
 city: New York
+url: https://example.com/api?query=value
+color: #FF5733
 
 # Example requiring double quotes
 message: "'Hello, World'"
 message: "First line\nNew line"
 indented: "  Leading spaces"
 indented: "Trailing spaces  "
+empty: ""
 ```
 
 ### Set (Parameters)

_pages/ko/docs/guides/introduce-apon.md

@@ -29,30 +29,57 @@ APON은 JSON과 YAML의 특징을 조합하여 가독성과 편의성을 높인
 | **항목 구분** | 쉼표 (`,`) | 줄바꿈 + 들여쓰기 | **줄바꿈** |
 | **주석** | 미지원 | 지원 (`#`) | 지원 (`#`) |
 
-가장 큰 차이점은 **구조를 정의하는 방식**과 **항목을 구분하는 방식**입니다. APON은 JSON처럼 괄호로 명시적인 구조를 만들지만, 항목 구분자로는 줄바꿈을 사용하여 가독성을 극대화합니다. 이는 줄바꿈과 들여쓰기의 조합으로 구조 전체를 정의하는 YAML과는 구분되는 특징입니다.
+가장 큰 차이점은 **구조를 정의하는 방식**과 **항목을 구분하는 방식**입니다. APON은 JSON처럼 괄호로 명시적인 구조를 만들지만, 항목 구분자로는 줄바꿈을 사용하여 가독성을 극대화합니다. 이는 줄바꿈과 들여쓰기의 조합으로 구조 전체를 정의하는 YAML과는 구분되는 특징입니다. 또한 콤마(`,`)를 사용하지 않음으로써 항목을 추가하거나 삭제할 때 발생할 수 있는 문법 오류(Trailing Comma 문제 등)를 방지하고, 버전 관리 시스템(Git 등)에서의 변경 이력을 깔끔하게 유지할 수 있습니다.
 
 ## 2. 기본 문법
 
+### 주석 (Comments)
+
+APON에서 주석은 반드시 **새로운 줄(New Line)**에 `#` 문자로 시작해야 합니다.
+파라미터 값 뒤에 `#`을 붙여 설명을 적는 **인라인 주석(Inline Comment)은 지원하지 않습니다.**
+
+이는 데이터 값에 `#` 문자(예: CSS 색상 코드 `#FFFFFF`, 해시태그 등)가 포함될 때, 불필요하게 따옴표로 감싸야 하는 번거로움을 없애고 입력의 자유도를 높이기 위함입니다.
+
+```apon
+# 올바른 주석 사용 예
+timeout: 30
+
+# 잘못된 주석 사용 예 (주석이 아닌 문자열 값으로 인식됨)
+# timeout의 값은 숫자 30이 아닌 문자열 "30 # 30 seconds"가 됩니다.
+timeout: 30 # 30 seconds
+```
+
 ### 단일 값 (Parameter)
 
 APON의 가장 기본적인 단위는 `이름: 값` 형식의 단일 값을 가질 수 있습니다.
+키와 값은 콜론(`:`)으로 구분되며, 콜론 이후부터 **행의 끝(End of Line)까지**가 모두 값으로 간주됩니다.
+
+이러한 특징 덕분에 다음과 같은 장점이 있습니다.
+*   값 중간에 공백이 있어도 따옴표가 필요 없습니다.
+*   URL이나 파일 경로처럼 특수문자가 포함된 값도 이스케이프 처리 없이 그대로 쓸 수 있습니다.
+*   값의 끝을 알리기 위해 콤마(`,`)를 입력할 필요가 없습니다.
+
 값(value)에 다음과 같은 특수 조건이 없는 한 따옴표(`"`)를 생략하는 것이 일반적입니다.
 
-*   값의 앞이나 뒤에 공백이 있는 경우
+*   값의 앞이나 뒤에 공백이 있는 경우 (중간 공백은 괜찮음)
 *   값에 작은따옴표(`'`)나 큰따옴표(`"`)가 포함된 경우
 *   값에 줄바꿈 문자(`\n`)가 포함된 경우
+*   값이 빈 문자열인 경우
 
 ```apon
-# 큰따옴표를 사용하지 않은 예
+# 큰따옴표를 사용하지 않은 예 (행 끝까지 값으로 인식)
 name: John Doe
 age: 30
 city: New York
+url: https://example.com/api?query=value
+color: #FF5733
 
 # 큰따옴표를 사용해야 하는 예
 message: "'Hello, World'"
 message: "First line\nNew line"
 indented: "  앞에 공백이 있음"
 indented: "뒤에 공백이 있음  "
+empty: ""
 ```
 
 ### 집합 (Parameters)
@@ -115,7 +142,6 @@ APON은 다양한 데이터 타입을 지원하며, `이름(타입): 값`의 형
 
 **`float`에 대한 중요 참고 사항:** 소수점 숫자를 `java.lang.Float`로 파싱하려면 APON 텍스트에서 `float`로 명시적으로 타입을 지정하거나(예: `score(float): 95.5`) `ValueType.FLOAT`를 가진 `ParameterKey`를 정의해야 합니다. 그렇지 않으면 소수점 숫자는 기본적으로 `java.lang.Double`로 처리됩니다.
 
-
 | Value Type | Java Object Type | 예시                            |
 | :--- | :--- |:------------------------------|
 | `string` | `java.lang.String` | `name(string): Hello, World.` |