From 7ae701e8c142fec85dc97f199107b60fbce8be96 Mon Sep 17 00:00:00 2001 From: Martino Ferrari Date: Mon, 2 Feb 2026 18:22:52 +0100 Subject: [PATCH] Auto doc... --- README.md | 2 +- docs/CONFIGURATION_GUIDE.md | 126 +++++++++++++++++++----------------- docs/TUTORIAL.md | 2 +- specification.md | 4 ++ 4 files changed, 72 insertions(+), 62 deletions(-) diff --git a/README.md b/README.md index b15aa90..01774c5 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ ## Features - **Portability**: A single statically compiled executable compatible with any Linux 3.2+ machine (as well as possible to compile and run on Windows and Mac OS X) -- **LSP Server**: Real-time syntax checking, validation, autocomplete, hover documentation, and navigation (Go to Definition/References). +- **LSP Server**: Real-time syntax checking, validation, autocomplete, hover documentation, navigation (Go to Definition/References), and Inlay Hints (inline types and evaluation). - **Builder**: Merges multiple configuration files into a single, ordered output file. - **Formatter**: Standardizes configuration file formatting. - **Validator**: Advanced semantic validation using [CUE](https://cuelang.org/) schemas, ensuring type safety and structural correctness. diff --git a/docs/CONFIGURATION_GUIDE.md b/docs/CONFIGURATION_GUIDE.md index 28109b2..c027100 100644 --- a/docs/CONFIGURATION_GUIDE.md +++ b/docs/CONFIGURATION_GUIDE.md @@ -27,15 +27,6 @@ Objects are defined using `+` (public/instantiated) or `$` (template/class-like) - References: `MyObject`, `MyObject.SubNode` - Arrays: `{ 1 2 3 }` or `{ "A" "B" }` -### Comments and Documentation -- Line comments: `// This is a comment` -- Docstrings: `//# This documents the following node`. These appear in hover tooltips. - -```marte -//# This is the main application -+App = { ... } -``` - ## 2. Signals and Data Flow Signals define how data moves between DataSources (drivers) and GAMs (algorithms). @@ -73,43 +64,26 @@ GAMs declare inputs and outputs. You can refer to signals directly or alias them } ``` -### Threading Rules -**Validation Rule**: A DataSource that is **not** marked as multithreaded (default) cannot be used by GAMs running in different threads within the same State. +## 3. Multi-file Projects -**Ordering Rule**: For `INOUT` signals (data dependency within a thread), the Producer GAM must appear **before** the Consumer GAM in the thread's `Functions` list. This ensures correct data flow within the cycle. This rule is skipped if the DataSource is marked as `multithreaded: true`. +You can split your configuration into multiple files. -To allow sharing, the DataSource class in the schema must have `#meta: multithreaded: true`. +### Namespaces +Use `#package` to define where the file's content fits in the hierarchy. -## 3. Schemas and Validation +**file1.marte** +```marte +#package MyApp.Controller ++MyController = { ... } +``` -`mdt` validates your configuration against CUE schemas. +This places `MyController` under `MyApp.Controller`. -### Built-in Schema -Common classes (`RealTimeApplication`, `StateMachine`, `IOGAM`, etc.) are built-in. +### Building +The `build` command merges all files. -### Custom Schemas -You can extend the schema by creating a `.marte_schema.cue` file in your project root. - -**Example: Adding a custom GAM** - -```cue -package schema - -#Classes: { - MyCustomGAM: { - // Metadata for Validator/LSP - #meta: { - direction: "INOUT" // "IN", "OUT", "INOUT" - multithreaded: false - } - - // Fields - Gain: float - Offset?: float // Optional - InputSignals: {...} - OutputSignals: {...} - } -} +```bash +mdt build -o final.marte src/*.marte ``` ## 4. Variables and Constants @@ -125,7 +99,7 @@ Variables can be defined at any level and can be overridden externally (e.g., vi +MyObject = { Class = Timer - Timeout = @Timeout + Timeout = $Timeout } ``` @@ -170,32 +144,51 @@ You can override variable values during build (only for `#var`): mdt build -vMyVar=200 src/*.marte ``` -### Docstrings -Docstrings (`//#`) work for variables and constants and are displayed in the LSP hover information. +## 5. Comments and Documentation -## 5. Multi-file Projects +- Line comments: `// This is a comment` +- Docstrings: `//# This documents the following node`. These appear in hover tooltips. -You can split your configuration into multiple files. - -### Namespaces -Use `#package` to define where the file's content fits in the hierarchy. - -**file1.marte** ```marte -#package MyApp.Controller -+MyController = { ... } +//# This is the main application ++App = { ... } ``` -This places `MyController` under `MyApp.Controller`. +Docstrings work for objects, fields, variables, and constants. -### Building -The `build` command merges all files. +## 6. Schemas and Validation -```bash -mdt build -o final.marte src/*.marte +`mdt` validates your configuration against CUE schemas. + +### Built-in Schema +Common classes (`RealTimeApplication`, `StateMachine`, `IOGAM`, etc.) are built-in. + +### Custom Schemas +You can extend the schema by creating a `.marte_schema.cue` file in your project root. + +**Example: Adding a custom GAM** + +```cue +package schema + +#Classes: { + MyCustomGAM: { + // Metadata for Validator/LSP + #meta: { + direction: "INOUT" // "IN", "OUT", "INOUT" + multithreaded: false + } + + // Fields + Gain: float + Offset?: float // Optional + InputSignals: {...} + OutputSignals: {...} + } +} ``` -## 6. Pragmas (Suppressing Warnings) +## 7. Pragmas (Suppressing Warnings) If validation is too strict, you can suppress warnings using pragmas (`//!`). @@ -230,7 +223,7 @@ If validation is too strict, you can suppress warnings using pragmas (`//!`). //! allow(implicit) ``` -## 7. Validation Rules (Detail) +## 8. Validation Rules (Detail) ### Data Flow Validation `mdt` checks for logical data flow errors: @@ -246,4 +239,17 @@ To allow sharing, the DataSource class in the schema must have `#meta: multithre ### Implicit vs Explicit Signals - **Explicit**: Signal defined in `DataSource.Signals`. - **Implicit**: Signal used in GAM but not defined in DataSource. `mdt` reports a warning unless suppressed. -- **Consistency**: All references to the same logical signal (same name in same DataSource) must share the same `Type` and size properties. \ No newline at end of file +- **Consistency**: All references to the same logical signal (same name in same DataSource) must share the same `Type` and size properties. + +## 9. Editor Features (LSP) + +The `mdt` LSP server provides several features to improve productivity. + +### Inlay Hints +Inlay hints provide real-time contextual information directly in the editor: + +- **Signal Metadata**: Signal usages in GAMs display their evaluated type and size, e.g., `Sig1` **`::uint32[10x1]`**. +- **Object Class**: References to objects show the object's class, e.g., `DataSource = ` **`FileReader::`** `DS`. +- **Expression Evaluation**: + - Complex expressions show their result at the end of the line, e.g., `Expr = 10 + 20` **` => 30`**. + - Variable references show their current value inline, e.g., `@MyVar` **`(=> 10)`**. diff --git a/docs/TUTORIAL.md b/docs/TUTORIAL.md index 55aff81..1e9a508 100644 --- a/docs/TUTORIAL.md +++ b/docs/TUTORIAL.md @@ -185,7 +185,7 @@ You can also use expressions for calculations: #let CycleTime: float64 = 1.0 / $SamplingFreq ``` -LSP hover will show you the evaluated values (e.g., `CycleTime: 0.01`). +LSP will show you the evaluated values directly in the code via **Inlay Hints** (e.g., `CycleTime: 0.01`) and in the hover documentation. ## Step 7: Advanced - Custom Schema diff --git a/specification.md b/specification.md index c93ebec..e612303 100644 --- a/specification.md +++ b/specification.md @@ -42,6 +42,10 @@ The LSP server should provide the following capabilities: - **Rename Symbol**: Rename an object, field, or reference across the entire project scope. - Supports renaming of Definitions (`+Name` or `Name`), preserving any modifiers (`+`/`$`). - Updates all references to the renamed symbol, including qualified references (e.g., `Pkg.Name`). +- **Inlay Hints**: Provide real-time contextual information inline. + - **Signal Metadata**: Displays `::TYPE[ELEMENTSxDIMENSIONS]` next to signal names. + - **Object Class**: Displays `CLASS::` before object references. + - **Evaluation**: Displays results of expressions (` => RESULT`) and variable references (`(=> VALUE)`). - **Code Snippets**: Provide snippets for common patterns (e.g., `+Object = { ... }`). - **Formatting**: Format the document using the same rules and engine as the `fmt` command.