From 4dd71fd0c1f3ceb16c4488b0c5f13f3655499b86 Mon Sep 17 00:00:00 2001 From: Patrick Stein Date: Wed, 1 Jul 2026 08:11:10 +0200 Subject: [PATCH 1/2] ESMIA-148 Add esnacc doc metadata Tag the esnacc README and FAQ with front matter for compiler and generated-output documentation routing. --- FAQ.md | 17 +++++++++++++++++ ReadMe.md | 18 ++++++++++++++++++ 2 files changed, 35 insertions(+) diff --git a/FAQ.md b/FAQ.md index 412a2b0c..7debcf03 100644 --- a/FAQ.md +++ b/FAQ.md @@ -1,3 +1,20 @@ +--- +title: estos-esnacc FAQ +scope: estos-esnacc +owner_repo: esnacc +entry_for: + - ASN.1 compiler background + - supported target languages + - licensing questions +purpose: Answer common questions about the enhanced ASN.1 compiler, supported targets, and licensing. +read_when: + - Investigating compiler capabilities or project background + - Updating generated target language or licensing documentation +related_docs: + - ReadMe.md + - ../docs/repos.md +--- + Frequently Asked Questions ========================== diff --git a/ReadMe.md b/ReadMe.md index 5a80ab45..80d8db8b 100644 --- a/ReadMe.md +++ b/ReadMe.md @@ -1,3 +1,21 @@ +--- +title: estos Enhanced Sample Neufeld ASN C Compiler +scope: estos-esnacc +owner_repo: esnacc +entry_for: + - ASN.1 compiler development + - target-language code generation + - protocol documentation generation +purpose: Explain how to build and use the enhanced ASN.1 compiler and its generated targets. +read_when: + - Changing compiler behavior or generated output + - Updating build instructions + - Investigating TypeScript, C++, Java, Swift, JSDoc, or OpenAPI generation +related_docs: + - ../AGENTS.md + - ../docs/repos.md +--- + # estos Enhanced Sample Neufeld ASN C Compiler This is the estos enhanced sample neufeld asn c compiler. It is an functional enriched fork of the original enhanced sample neufeld asn c compiler offering: From b7b68a331c809097bc8dbc42358d01f216aa76d4 Mon Sep 17 00:00:00 2001 From: Patrick Stein Date: Wed, 1 Jul 2026 08:35:39 +0200 Subject: [PATCH 2/2] ESMIA-148 Updated documentation --- FAQ.md | 19 ++++++++++++++--- ReadMe.md | 21 +++++++++++++++---- cpp-lib/tests/runtime_correctness_notes.md | 16 ++++++++++++++ samples/readme.md | 17 +++++++++++++++ samples/ts-microservice/node-server/README.md | 16 ++++++++++++++ samples/ts-microservice/readme.md | 17 +++++++++++++++ 6 files changed, 99 insertions(+), 7 deletions(-) diff --git a/FAQ.md b/FAQ.md index 7debcf03..8e792e51 100644 --- a/FAQ.md +++ b/FAQ.md @@ -12,7 +12,7 @@ read_when: - Updating generated target language or licensing documentation related_docs: - ReadMe.md - - ../docs/repos.md + - samples/readme.md --- Frequently Asked Questions @@ -47,16 +47,29 @@ A: estos eSNACC is the estos enhanced Sample Neufeld ASN.1 C Compiler. It is a * Structure definitions * JSON and BER encoder/decoders * ROSE client/server implementation (complete stubs) + * C + * Structure definitions + * BER encoder/decoders + * C# + * Structure definitions * Delphi * Structure definitions * JAVA * Structure definitions + * Kotlin + * Structure definitions * JavaScript JSON * Structure definitions + * JavaScript ES6 + * Structure definitions * SWIFT * Structure definitions + * IDL + * Interface definitions * JSDOC * JSON formatted Documentation generated based on the documentation inside the asn1 files + * OpenApi + * OpenApi JSON documentation generated based on documentation inside the ASN.1 files ### Q: What versions of ASN.1 does the estos eSNACC interoperate with? @@ -67,8 +80,8 @@ A: The estos eSNACC can support most of X.608/X.609 for Basic Encoding Rules. S ### Q: Which programming languages does the estos eSNACC target? -A: Currently, the estos eSNACC mainly targets C++ and typescript but other languages are also supported. - Check the compiler back-ends directory for the currently adresses languages. +A: Currently, the estos eSNACC mainly targets C++ and Typescript but other languages are also supported. + Check the compiler back-ends directory for the currently addressed languages. However the different languages may not support the full featureset like the c++ and typescript implementation. diff --git a/ReadMe.md b/ReadMe.md index 80d8db8b..93be737d 100644 --- a/ReadMe.md +++ b/ReadMe.md @@ -10,10 +10,11 @@ purpose: Explain how to build and use the enhanced ASN.1 compiler and its genera read_when: - Changing compiler behavior or generated output - Updating build instructions - - Investigating TypeScript, C++, Java, Swift, JSDoc, or OpenAPI generation + - Investigating TypeScript, C++, C, C#, Java, Kotlin, Swift, JSDoc, IDL, or OpenAPI generation related_docs: - - ../AGENTS.md - - ../docs/repos.md + - FAQ.md + - samples/readme.md + - cpp-lib/tests/runtime_correctness_notes.md --- # estos Enhanced Sample Neufeld ASN C Compiler @@ -22,6 +23,9 @@ It is an functional enriched fork of the original enhanced sample neufeld asn c * Documented source code, based on the documentation from the asn1 source files * Creating documentation based on the documentation from the asn1 source files * Additional supported target languages + * C + * Structure definitions + * BER encoder/decoders * Typescript (main maintained language) * Structure definitions * JSON and BER encoder/decoders @@ -31,14 +35,22 @@ It is an functional enriched fork of the original enhanced sample neufeld asn c * Structure definitions * JSON and BER encoder/decoders * ROSE client/server implementation (complete stubs) + * C# + * Structure definitions * Delphi * Structure definitions * JAVA * Structure definitions + * Kotlin + * Structure definitions * JavaScript JSON * Structure definitions + * JavaScript ES6 + * Structure definitions * SWIFT * Structure definitions + * IDL + * Interface definitions * JSDOC * JSON formatted Documentation generated based on the documentation inside the asn1 files * OpenApi @@ -54,12 +66,13 @@ Other languages just offer to get created structures which need to get serialize # Getting started You need to compile the compiler or use a precompiled version of it. The samples folder offers examples on the usage for the different supported languages. These folders show some sample asn1 files, the command line and the expected output of the compiler. +See [samples/readme.md](samples/readme.md) for the current TypeScript microservice sample layout and required Node/pnpm setup. # Building the compiler ## Prerequesites to compile the compiler * Have cmake installed * https://cmake.org - * at least V3.21 + * at least V3.20 * available in the path ## Command line diff --git a/cpp-lib/tests/runtime_correctness_notes.md b/cpp-lib/tests/runtime_correctness_notes.md index 5c38b91b..20cab08b 100644 --- a/cpp-lib/tests/runtime_correctness_notes.md +++ b/cpp-lib/tests/runtime_correctness_notes.md @@ -1,3 +1,19 @@ +--- +title: C++ Runtime Correctness Notes +scope: cpp-lib/tests +owner_repo: esnacc +entry_for: + - C++ runtime behavior + - runtime correctness tests + - ROSE telemetry and shutdown semantics +purpose: Record intended C++ runtime semantics before tests or implementation are tightened. +read_when: + - Changing cpp-lib runtime behavior, telemetry, shutdown, or decode-error handling + - Adding or reviewing runtime correctness tests +related_docs: + - ../../ReadMe.md +--- + # Runtime Correctness Notes This note records the intended semantics for selected `cpp-lib` runtime behaviors diff --git a/samples/readme.md b/samples/readme.md index 07b8a75a..9ab32b67 100644 --- a/samples/readme.md +++ b/samples/readme.md @@ -1,3 +1,20 @@ +--- +title: esnacc Samples Overview +scope: samples +owner_repo: esnacc +entry_for: + - sample applications + - TypeScript microservice sample + - generated runtime code examples +purpose: Route readers to the sample projects that demonstrate generated esnacc code. +read_when: + - Running or updating esnacc samples + - Changing TypeScript sample package layout or integration-test flow +related_docs: + - ../ReadMe.md + - ts-microservice/readme.md +--- + # Samples This folder contains samples that show how to use the snacc compiler and the generated runtime code. diff --git a/samples/ts-microservice/node-server/README.md b/samples/ts-microservice/node-server/README.md index ac8fff0f..1ff170b8 100644 --- a/samples/ts-microservice/node-server/README.md +++ b/samples/ts-microservice/node-server/README.md @@ -1,3 +1,19 @@ +--- +title: TypeScript Node Server Sample +scope: samples/ts-microservice/node-server +owner_repo: esnacc +entry_for: + - TypeScript ROSE server sample + - Express REST and WebSocket handlers + - generated server stub usage +purpose: Document the Node server package used by the TypeScript microservice sample. +read_when: + - Updating node-server handlers, configuration, generated stubs, or integration-test behavior +related_docs: + - ../readme.md + - ../../readme.md +--- + # estos NodeJS server sample (`node-server`) [TOC] diff --git a/samples/ts-microservice/readme.md b/samples/ts-microservice/readme.md index 4ef041f4..098961be 100644 --- a/samples/ts-microservice/readme.md +++ b/samples/ts-microservice/readme.md @@ -1,3 +1,20 @@ +--- +title: TypeScript Microservice Sample +scope: samples/ts-microservice +owner_repo: esnacc +entry_for: + - TypeScript generated stubs + - Node server and client integration tests + - browser demo and OpenAPI sample +purpose: Explain the TypeScript microservice sample layout, preparation steps, and verification flow. +read_when: + - Updating TypeScript code generation samples + - Running node-server, node-client, browser-client, or OpenAPI examples +related_docs: + - ../readme.md + - node-server/README.md +--- + # Typescript based microservice sample This sample shows how generated TypeScript ASN.1 stubs are used end-to-end: a Node server, a browser demo, and automated integration tests.