improve documentation to explain the sort flag (generated by windsurf)

README.md

@@ -76,15 +76,56 @@ How to run the binary
             [default: unsorted]
 
             Possible values:
-            - unsorted: the order remains as found in document
-            - name:     sort attributes and children by name (as given in XML). attributes and children are not merged
+            - unsorted: the order remains as found in document (ideal for mixed content XML)
+            - name:     sort attributes and children by name (ideal for data-oriented XML)
 
     -h, --help
             Print help (see a summary with '-h')
 
     -V, --version
             Print version
 ```
+
+## Sorting Options
+
+### Document Order (default) - `--sort unsorted`
+Preserves the original order of elements as they appear in the XML document. This is ideal for:
+
+- **Mixed content XML** with alternating element types
+- **Document-oriented XML** where element sequence matters
+- **XML with comments, processing instructions, or mixed text/elements**
+
+Example:
+```xml
+<doc>
+  <comment>A comment.</comment>
+  <sentence>First sentence.</sentence>
+  <break/>
+  <sentence>Second sentence.</sentence>
+  <comment>Another comment.</comment>
+</doc>
+```
+
+With `--sort unsorted`, the generated struct preserves this sequence.
+
+### Alphabetical Order - `--sort name`
+Sorts attributes and children by name for improved readability. This is ideal for:
+
+- **Data-oriented XML** where element order doesn't matter
+- **Configuration files** and **structured data**
+- **API responses** where field organization improves readability
+
+Example:
+```xml
+<user>
+  <email>[email protected]</email>
+  <id>123</id>
+  <name>John Doe</name>
+  <phone>555-1234</phone>
+</user>
+```
+
+With `--sort name`, the generated struct fields are sorted alphabetically: `email`, `id`, `name`, `phone`.
 # Web Assembly
 
 You can take a look at the result of xml_schema_generator at [xml_schema_generator Github Pages](https://thomblin.github.io/xml_schema_generator/)
@@ -98,7 +139,7 @@ Just create a well tested Pull Request in github
 # Implemented features
 
 ☑ parse UTF-8 xml file
- 
+
 ☑ generate Rust struct
 
 ☑ detect optional attributes
@@ -136,7 +177,7 @@ Just create a well tested Pull Request in github
 ☐ improve performance
 
 ☐ support UTF-16
- 
+
 ☐ suppport ISO_2022_JP
 
 # License

src/args.rs

@@ -12,7 +12,7 @@ pub struct Args {
     /// define the #derive attribute to be added to each resulting struct
     #[clap(short, long, default_value = "Serialize, Deserialize")]
     pub derive: String,
-    /// sorting order for attributes and children
+    /// sorting order for attributes and children (use unsorted for mixed content, name for data-oriented XML)
     #[clap(short, long, default_value_t, value_enum)]
     pub sort: SortByArg,
     /// xml file that shall be parsed
@@ -24,10 +24,10 @@ pub struct Args {
 /// supported parser variants
 #[derive(clap::ValueEnum, Clone, Default, Debug)]
 pub enum SortByArg {
-    /// the order remains as found in document
+    /// preserve document order (ideal for mixed content XML with comments, text, and alternating elements)
     #[default]
     Unsorted,
-    /// sort attributes and children by name (as given in XML). attributes and children are not merged
+    /// sort alphabetically by name (ideal for data-oriented XML, config files, and API responses)
     Name,
 }