mxaccessgw/StyleGuide.md

Documentation Style Guide

This guide defines writing conventions and formatting rules for all MXAccess Gateway (mxaccessgw) documentation.

Tone and Voice

Be Technical and Direct

Write for developers who are familiar with .NET. Don't explain basic concepts like dependency injection or async/await unless they're used in an unusual way.

Good:

The SessionManager launches one worker per session and tracks it through the session state machine.

Avoid:

The SessionManager is a really powerful component that helps manage all your MXAccess connections efficiently!

Explain "Why" Not Just "What"

Document the reasoning behind patterns and decisions, not just the mechanics.

Good:

The worker pumps Windows messages on its STA thread because a plain blocking queue does not let MXAccess COM events deliver.

Avoid:

The worker pumps Windows messages on its STA thread.

Use Present Tense

Describe what the code does, not what it will do.

Good:

The gateway terminates orphaned workers on startup.

Avoid:

The gateway will terminate orphaned workers on startup.

No Marketing Language

This is internal technical documentation. Avoid superlatives and promotional language.

Avoid: "powerful", "robust", "cutting-edge", "seamless", "blazing fast"

Formatting Rules

File Names

Use PascalCase.md for all documentation files:

• Sessions.md
• GatewayConfiguration.md
• WorkerSta.md
• Diagnostics.md

Headings

• H1 (#): Document title only, Title Case
• H2 (##): Major sections, Title Case
• H3 (###): Subsections, Sentence case
• H4+ (####): Rarely needed, Sentence case

# Gateway Configuration

## Session Options

### Setting the lease timeout

#### Default values

Code Blocks

Always specify the language:

```csharp
public sealed class GatewaySession { }
```

```json
{
  "MxGateway": { "Sessions": { "MaxConcurrent": 8 } }
}
```

```powershell
dotnet build src/ZB.MOM.WW.MxGateway.slnx
```

Supported languages: csharp, json, bash, powershell, xml, sql, text, rust, python, go, proto, html, css, toml.

Code Snippets

Length: 5-25 lines is typical. Shorter for simple concepts, longer for complete examples.

Context: Include enough to understand where the code lives:

// Good - shows class context
public sealed class GatewaySession
{
    public GatewaySession(SessionId sessionId, WorkerPipeSession pipe)
    {
        _sessionId = sessionId;
        _pipe = pipe;
    }
}

// Avoid - orphaned snippet
_pipe = pipe;

Accuracy: Only use code that exists in the codebase. Never invent examples.

Lists

Use bullet points for unordered items:

- First item
- Second item
- Third item

Use numbers for sequential steps:

1. Do this first
2. Then do this
3. Finally do this

Tables

Use tables for structured reference information:

| Option | Default | Description |
|--------|---------|-------------|
| `MaxConcurrent` | `8` | Maximum simultaneous sessions |
| `LeaseTimeoutSeconds` | `60` | Idle lease before sweep |

Inline Code

Use backticks for:

• Class names: SessionManager
• Method names: KillWorkerAsync()
• File names: appsettings.json
• Configuration keys: MxGateway:Sessions:MaxConcurrent
• Command-line commands: dotnet build

Links

Use relative paths for internal documentation:

[See the architecture overview](./gateway.md)
[Configuration options](./docs/GatewayConfiguration.md)

Use descriptive link text:

<!-- Good -->
See the [Gateway Configuration](./docs/GatewayConfiguration.md) documentation.

<!-- Avoid -->
See [here](./docs/GatewayConfiguration.md) for more.

Structure Conventions

Document Opening

Every document starts with:

1. H1 title
2. 1-2 sentence description of purpose

# Worker STA Thread

The worker owns one MXAccess COM instance on a dedicated STA thread and pumps
Windows messages so MXAccess events deliver.

Section Organization

Organize content from general to specific:

1. Overview/introduction
2. Key concepts (if needed)
3. Basic usage
4. Advanced usage
5. Configuration
6. Troubleshooting
7. Related documentation

Code Example Placement

Place code examples immediately after the concept they illustrate:

## Session Close

The gateway closes a session by killing its worker behind the close gate:

```csharp
await session.KillWorkerWithCloseGateAsync(cancellationToken);

The close gate serializes concurrent close attempts...

### Related Documentation Section

End each document with links to related topics:

```markdown
## Related Documentation

- [Sessions](./docs/Sessions.md)
- [Worker STA Thread](./docs/WorkerSta.md)
- [Gateway Configuration](./docs/GatewayConfiguration.md)

Naming Conventions

Match Code Exactly

Use the exact names from source code:

• MxStatusProxy not "MX status proxy"
• SessionManager not "session manager"
• OrphanWorkerTerminator not "orphan worker terminator"

Acronyms

Spell out on first use, then use acronym:

Single-threaded apartment (STA) threads serialize COM calls. STA message pumping lets MXAccess events deliver...

Common acronyms that don't need expansion:

• API
• JSON
• SQL
• HTTP/HTTPS
• COM
• gRPC
• IPC
• STA
• UI

File Paths

Use forward slashes and backticks:

• src/ZB.MOM.WW.MxGateway.Server/
• appsettings.json
• docs/GatewayConfiguration.md

What to Avoid

Don't Document the Obvious

<!-- Avoid -->
## Constructor

The constructor creates a new instance of the class.

<!-- Better - only document if there's something notable -->
## Constructor

The constructor accepts a `WorkerPipeSession`, which must be connected before
the session transitions out of `Handshaking`.

Don't Duplicate Source Code Comments

If code has good comments, reference the file rather than copying:

See SessionManager.cs for the open-failure rollback order.

Don't Include Temporary Information

Avoid dates, version numbers, or "coming soon" notes that will become stale.

Don't Over-Explain .NET Basics

Assume readers know:

• Dependency injection
• async/await
• LINQ
• ASP.NET Core middleware pipeline
• gRPC service basics

Related Documentation

• Architecture overview
• Gateway Configuration
• C# Style Guide
• Go Style Guide, Java Style Guide, Python Style Guide, Rust Style Guide, Protobuf Style Guide