update modules

Author: mertcandav

.vitepress/config.mts

@@ -337,6 +337,7 @@ export default defineConfig({
               link: '/packages/modules/',
               items: [
                 { text: 'Internal Packages', link: '/packages/modules/internal-packages' },
+                { text: 'Specification', link: '/packages/modules/specification' },
               ],
             },
             { text: 'Using Packages', link: '/packages/using-packages' },

src/getting-started/first-project.md

@@ -1,6 +1,6 @@
 # First Project
 
-In this section, you will quickly create your first Jule project. You’ll learn the language details in later sections. This part is meant for a quick start and first look.
+In this section, you will quickly create your first Jule project. You'll learn the language details in later sections. This part is meant for a quick start and first look.
 
 First, choose a workspace and create a `main.jule` file. Jule source code is written in files with the `.jule` extension. The compiler only works with these files. The `main.jule` file you create will be the file where you write your program.
 
@@ -10,7 +10,7 @@ fn main() {
 	println("hello world")
 }
 ```
-Once you've written your code in the `main.jule` file, you’re ready to compile. With the compiler, you perform package-based compilation. [Packages](/packages/) are a core part of Jule’s project management. The directory you compile from is treated as the main package of your program.
+Once you've written your code in the `main.jule` file, you're ready to compile. With the compiler, you perform package-based compilation. [Packages](/packages/) are a core part of Jule's project management. The directory you compile from is treated as the main package of your program.
 
 To compile your project with the compiler, you can use a command like the following:
 ```

src/packages/modules/index.md

@@ -1,16 +1,16 @@
 # Modules
 
-Modules are the recommended way to organize a Jule project. A module defines the project’s structure and groups related packages in a safe, modular fashion. This enables the use of subpackages, helps maintain clean organization, and is especially useful when designing third-party packages.
+Modules are the recommended way to organize a Jule project. A module defines the project's structure and groups related packages in a safe, modular fashion. This enables the use of subpackages, helps maintain clean organization, and is especially useful when designing third-party packages.
 
-Modules standardize code layout and establish the main structure of a project. The module file acts as the entry point: the directory containing it is treated as the module’s root, and the compiler processes your code accordingly.
+Modules standardize code layout and establish the main structure of a project. The module file acts as the entry point: the directory containing it is treated as the module's root, and the compiler processes your code accordingly.
 
 ## Initialize a Module
 
-To create a module, run the compiler command in the target directory. This generates the required files and marks the current working directory as the root of your module.
+To create a module with a name, run the compiler command in the target directory. This generates the required files and marks the current working directory as the root of your module.
 
 For example:
 ```
-$ julec mod init
+$ julec mod init mylib
 ```
 
 ## Module Files
@@ -19,7 +19,7 @@ A module is defined by a file named `jule.mod`. Its presence marks the directory
 
 ## Using Modules
 
-Modules are not optional if you want to use Jule’s testing features—without them, testing becomes more difficult and less functional. See [writing tests](/debugging/testing/writing-tests#modules) for details.
+Modules are not optional if you want to use Jule's testing features—without them, testing becomes more difficult and less functional. See [writing tests](/debugging/testing/writing-tests#modules) for details.
 
 For most projects, subpackages are essential to maintainable development. Modules are required to organize and import these subpackages.
 
@@ -32,11 +32,11 @@ project/
 │  ├─ bar/
 │  │  └─ bar.jule
 │  └─ foo.jule
-├─ jule.mod
+├─ jule.mod (name is baz)
 └─ main.jule
 ```
 
-Here, `main.jule` must import the `bar` package as `"project/foo/bar"`, because the module root is `project/`. Likewise, the `foo` package must also use `"project/foo/bar"`, not just `bar`.
+Here a module with name `baz`, the file `main.jule` must import the `bar` package as `"baz/foo/bar"`, because the module name is `baz`. Likewise, the `foo` package must also use `"baz/foo/bar"`, not just `bar`.
 
 ## Nested Modules
 
@@ -51,11 +51,11 @@ project/
 │  ├─ bar/
 │  │  └─ bar.jule
 │  ├─ foo.jule
-│  └─ jule.mod
-├─ jule.mod
+│  └─ jule.mod (name is foo)
+├─ jule.mod (name is baz)
 └─ main.jule
 ```
 
-In this structure `main.jule` located in the root module, imports bar as `"project/foo/bar"`. The` foo` package, however, contains its own `jule.mod`, making it a separate module. Inside `foo`, the `bar` package is imported as `"foo/bar"`.
+In this structure `main.jule` located in the root module, imports bar as `"baz/foo/bar"`. The `foo` package, however, contains its own `jule.mod`, making it a separate module. Inside `foo`, the `bar` package is imported as `"foo/bar"`.
 
 This design makes the `foo` package self-contained and portable. Thanks to its own module file, it can be moved or reused in different projects without breaking imports.

src/packages/modules/internal-packages.md

@@ -16,4 +16,4 @@ project/
 └─ main.jule
 ```
 
-The `foo` package has its own module (`foo/jule.mod`), making `foo` the root of its module. The `internal` package under `foo` is internal to this module. All code within the `foo` module can access it. The `main.jule` file belongs to a different module (the project root module) and cannot access `foo/internal`, even though it can import the `foo` package itself.
+The `foo` package has its own module (`foo/jule.mod`), making `foo` the root of its module. The `internal` package under `foo` is internal to this module. All code within the `foo` module can access it. The `main.jule` file belongs to a different module (the project root module) and cannot access `foo/internal` directory, even though it can import the `foo` package itself.

src/packages/modules/specification.md

@@ -0,0 +1,15 @@
+# Specification
+
+Modules are represented with `jule.mod` files. The directories containing these files are treated as root directories, and their subdirectories behave as subpackages. Subpackages can also have their own dedicated modules.
+
+## Module Names
+
+Every module must have a module name. Module names define how the root directory of a module is represented in the import paths. This is important for portability, as it ensures a definitive name is used regardless of the root module directory.
+
+In the module file, it is represented as follows:
+```
+module mylib
+```
+In the example above, the module name is specified as `mylib`.
+
+A module name may only consist of letters, digits, `_`, or `.` characters. The first character must be either a letter or an `_`.

src/packages/using-packages.md

@@ -32,7 +32,7 @@ Having any native module package `std` will make it unreachable. Because there i
 ### Module
 Your own project may not consist of only one package, the main one. You may want to include different packages in your project. It is a useful action to use separate packages for the organization of the project. Jule recognizes subpackages in your project's main package and allows you to import those subpackages.
 
-For example, your main package is head directory. This package is your entry package for project. But for this, your main program must also be a module. For more information about modules, you can look at the [modules](/packages/modules/) section.
+For example, your main package is the `head` directory. This package is your entry package for your project. But for this, your main program must also be a module. For more information about modules, you can look at the [modules](/packages/modules/) section.
 
 Your example project tree:
 ```
@@ -43,7 +43,7 @@ head/
 │  │  └─ bar.jule
 │  ├─ README.md
 │  └─ foo.jule
-├─ jule.mod
+├─ jule.mod (name is head)
 ├─ LICENSE
 └─ main.jule
 ```

src/some-questions.md

@@ -318,4 +318,4 @@ fn main() {
 	foo(fn|mut x| { *x++ })
 }
 ```
-In the example above, the `foo` function takes an anonymous function as a parameter and allows the `x` parameter to be used mutably. However, if you look at the first call in the example, you’ll see it actually only makes a `println` call. In this case, there is no need for the parameter to be mutable, and this does not compromise Jule's mutability safety. However, in the second call, the value of the `x` parameter is modified, so mutability is required.
+In the example above, the `foo` function takes an anonymous function as a parameter and allows the `x` parameter to be used mutably. However, if you look at the first call in the example, you'll see it actually only makes a `println` call. In this case, there is no need for the parameter to be mutable, and this does not compromise Jule's mutability safety. However, in the second call, the value of the `x` parameter is modified, so mutability is required.

src/the-mission.md

@@ -32,7 +32,7 @@ To achieve memory efficiency, some decisions must be made such as avoiding featu
 Rust is known for its strict safety guarantees, and it does an excellent job. However, as mentioned before, there are many different approaches.
 Jule is not as rigid as Rust; it's designed to be more flexible, similar to Go.
 
-Go provides runtime safety, catching errors like boundary violations and nil pointer dereferencing. However, it doesn’t enforce data race safety, even though concurrency is a key feature. This assumes the developer will act carefully and responsibly.
+Go provides runtime safety, catching errors like boundary violations and nil pointer dereferencing. However, it doesn't enforce data race safety, even though concurrency is a key feature. This assumes the developer will act carefully and responsibly.
 
 Jule adopts a similar philosophy but is slightly stricter than Go. While it assumes developers will avoid issues like data races, it also performs some static safety analysis at compile-time.