refine: explicate more details from the style guide

Include much of the details from eka's style guide directly in the EEP
to be a bit more self-contained.

Author: nrdxp

eeps/0031-org-wide-rust-style-guide.md

@@ -26,7 +26,83 @@ This EEP proposes the adoption of a standardized style guide and formatting conf
 
 ### 1. Official Style Guide
 
-The existing [STYLE_GUIDE.md](https://github.com/ekala-project/eka/blob/master/STYLE_GUIDE.md) will be adopted as the canonical style guide for all Rust projects. It codifies conventions for file structure, item ordering, sorting rules, and documentation, which are not covered by automated tooling.
+The following style guide (inspired by eka's [`STYLE_GUIDE.md`](https://github.com/ekala-project/eka/blob/master/STYLE_GUIDE.md)) will be adopted as the canonical style guide for all Rust projects. It codifies conventions for file structure, item ordering, sorting rules, and documentation, which are not covered by automated tooling.
+
+#### 1.1. File Structure and Item Order
+
+All Rust module files (`.rs`) must follow a strict top-level item order to ensure predictability and ease of navigation. The canonical order is as follows:
+
+1.  **Module-level documentation (`//!`)**: Explains the purpose and scope of the module.
+2.  **Outer attributes (`#![...]`)**: Compiler directives like `#![deny(missing_docs)]`.
+3.  **`use` declarations**: External and internal imports.
+4.  **Public re-exports (`pub use`)**: Items re-exported from other modules.
+5.  **Submodules (`mod`)**: Child module declarations.
+6.  **Constants (`const`)**: Compile-time constants.
+7.  **Static variables (`static`)**: Globally allocated variables.
+8.  **Types**: `struct`, `enum`, and `type` aliases.
+9.  **Traits**: Trait definitions.
+10. **Trait implementations and `impl` blocks**: Implementations of traits and inherent methods.
+11. **Free-standing functions**: Module-level functions.
+12. **Tests (`#[cfg(test)]` modules)**: Unit and integration tests for the module.
+
+#### 1.2. Sorting and Grouping Rules
+
+Within each category, items must be sorted to maintain a consistent structure.
+
+##### `use` Declarations
+
+`use` declarations are grouped in the following order, with each group sorted alphabetically:
+
+1.  **`std`**: Standard library imports.
+2.  **External Crates**: Third-party dependencies.
+3.  **Local Modules**: Project-internal imports, starting with `crate::` or `super::`.
+
+Example:
+
+```rust
+use std::collections::HashMap;
+use std::path::PathBuf;
+
+use anyhow::Result;
+use log::info;
+
+use crate::core::Atom;
+use super::utils::helper_function;
+```
+
+##### Other Items
+
+All other top-level items—including modules, constants, types, traits, and functions—must be sorted alphabetically by their identifier.
+
+##### Visibility
+
+Within any given category, **public (`pub`) items must always be placed before private items**. This rule applies before alphabetical sorting. For example, a public function `alpha` would come before a private function `beta`, but also before a public function `zeta`.
+
+Example:
+
+```rust
+// Public items first, sorted alphabetically
+pub const MAX_RETRIES: u32 = 3;
+pub fn get_config() -> Config { /* ... */ }
+
+// Private items next, sorted alphabetically
+const DEFAULT_TIMEOUT: u64 = 10;
+fn process_data() { /* ... */ }
+```
+
+#### 1.3. Documentation Comments
+
+Clear and comprehensive documentation is mandatory for maintaining a high-quality codebase.
+
+- **All public items** (modules, functions, types, traits, constants) must have descriptive documentation comments (`///`).
+- **Module-level documentation (`//!`)** is required for every module. It should provide a high-level overview of the module's responsibilities and how it fits into the larger system.
+- Comments should be clear, concise, and sufficient for a developer to understand the item's purpose and usage without needing to read the underlying source code.
+
+#### 1.4. General Guidelines
+
+- **Use `rustfmt`**: This project uses an opinionated `rustfmt.toml` configuration to enforce a consistent code style. Running `cargo fmt` will automatically handle much of the formatting for you. However, the guidelines in this document (especially regarding item order and documentation) must still be followed manually.
+- **Preserve Semantics**: Never alter the meaning or behavior of the code purely for the sake of conforming to style.
+- **Preserve Comments and Attributes**: When reordering items, ensure that all associated documentation, comments (`//`), and attributes (`#[...]`) are moved along with the item they describe.
 
 ### 2. Standard `rustfmt` Configuration