diff --git a/FAQ.md b/FAQ.md index 412a2b0..8e792e5 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 + - samples/readme.md +--- + Frequently Asked Questions ========================== @@ -30,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? @@ -50,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 5a80ab4..93be737 100644 --- a/ReadMe.md +++ b/ReadMe.md @@ -1,9 +1,31 @@ +--- +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++, C, C#, Java, Kotlin, Swift, JSDoc, IDL, or OpenAPI generation +related_docs: + - FAQ.md + - samples/readme.md + - cpp-lib/tests/runtime_correctness_notes.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: * 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 @@ -13,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 @@ -36,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 5c38b91..20cab08 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 07b8a75..9ab32b6 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 ac8fff0..1ff170b 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 4ef041f..098961b 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.