Skip to content

Commit 1e0033b

Browse files
mjambonclaude
mjambon
and
claude
authored
Add feature support matrix to documentation (#461)
* Add feature support matrix to documentation Adds internal/src/main.ml, a small OCaml program that encodes which ATD features each backend supports (Yes/Planned/No) and generates an RST page. Run `make` in internal/ to regenerate doc/support-matrix.rst. The matrix is included in the ATD Project page in the Sphinx docs. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * support-matrix: replace 'shared' with 'binary_serialization' 'shared' was specific to Biniou/OCaml and is no longer supported. Replace it with 'binary_serialization' (Biniou format), supported only by atdgen. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * Fix support matrix data * Update copyright notice in docs --------- Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
1 parent 923ae0f commit 1e0033b

File tree

6 files changed

+398
-2
lines changed

6 files changed

+398
-2
lines changed

‎doc/atd-project.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,3 +21,5 @@ Some properties of interest of ATD schemas include:
2121
* support for sum types aka algebraic data types or tagged unions
2222
* options to select alternate representations than the default, e.g.
2323
use a JSON object rather than an array of pairs
24+
25+
.. include:: support-matrix.rst

‎doc/conf.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -45,8 +45,8 @@
4545

4646
# General information about the project.
4747
project = 'atd'
48-
copyright = u'2010-2012 MyLife; 2012-2018 Martin Jambon & contributors'
49-
author = u'Martin Jambon, John Billings & contributors'
48+
copyright = u'2010-2012 MyLife; 2020-2026 Semgrep; 2012-2026 Martin Jambon & contributors'
49+
author = u'Martin Jambon & contributors'
5050

5151
# The language for content autogenerated by Sphinx. Refer to documentation
5252
# for a list of supported languages.

‎doc/support-matrix.rst‎

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
.. Generated by internal/src/main.ml. Do not edit directly.
2+
Run 'make' in internal/ to regenerate.
3+
4+
Feature Support Matrix
5+
======================
6+
7+
For each ATD feature, target languages are grouped by support level.
8+
9+
Basic types
10+
~~~~~~~~~~~
11+
12+
unit, bool, int, float, string
13+
14+
**Supported:** atdml (OCaml), atdgen (OCaml), atdpy (Python), atdts (TypeScript), atdj (Java), atds (Scala), atdd (Dart), atdcpp (C++)
15+
16+
Abstract type
17+
~~~~~~~~~~~~~
18+
19+
Any JSON value (abstract keyword)
20+
21+
**Supported:** atdml (OCaml), atdgen (OCaml), atdpy (Python), atdts (TypeScript), atdj (Java), atds (Scala), atdd (Dart), atdcpp (C++)
22+
23+
List / array
24+
~~~~~~~~~~~~
25+
26+
The list type constructor
27+
28+
**Supported:** atdml (OCaml), atdgen (OCaml), atdpy (Python), atdts (TypeScript), atdj (Java), atds (Scala), atdd (Dart), atdcpp (C++)
29+
30+
Option type
31+
~~~~~~~~~~~
32+
33+
ATD-style "None" / ["Some", x] encoding
34+
35+
**Supported:** atdml (OCaml), atdgen (OCaml), atdpy (Python), atdts (TypeScript), atdj (Java), atds (Scala), atdd (Dart), atdcpp (C++)
36+
37+
Nullable
38+
~~~~~~~~
39+
40+
JSON null <-> None, other value <-> Some x
41+
42+
**Supported:** atdml (OCaml), atdgen (OCaml), atdpy (Python), atdts (TypeScript), atdj (Java), atds (Scala), atdd (Dart), atdcpp (C++)
43+
44+
Wrap type
45+
~~~~~~~~~
46+
47+
Custom type wrappers ('a wrap)
48+
49+
**Supported:** atdml (OCaml), atdgen (OCaml), atdts (TypeScript), atdd (Dart), atdcpp (C++)
50+
51+
**Not yet:** atdpy (Python), atdj (Java), atds (Scala)
52+
53+
Records
54+
~~~~~~~
55+
56+
Record types with named fields
57+
58+
**Supported:** atdml (OCaml), atdgen (OCaml), atdpy (Python), atdts (TypeScript), atdj (Java), atds (Scala), atdd (Dart), atdcpp (C++)
59+
60+
Sum types
61+
~~~~~~~~~
62+
63+
Tagged unions / variants
64+
65+
**Supported:** atdml (OCaml), atdgen (OCaml), atdpy (Python), atdts (TypeScript), atdj (Java), atds (Scala), atdd (Dart), atdcpp (C++)
66+
67+
Tuples
68+
~~~~~~
69+
70+
Fixed-arity product types
71+
72+
**Supported:** atdml (OCaml), atdgen (OCaml), atdpy (Python), atdts (TypeScript), atdj (Java), atds (Scala), atdd (Dart), atdcpp (C++)
73+
74+
Parametric types
75+
~~~~~~~~~~~~~~~~
76+
77+
Generic / parameterized type definitions
78+
79+
**Supported:** atdml (OCaml), atdgen (OCaml), atdpy (Python), atdts (TypeScript), atdj (Java), atds (Scala), atdd (Dart), atdcpp (C++)
80+
81+
Type aliases
82+
~~~~~~~~~~~~
83+
84+
Simple aliases (type t = int list)
85+
86+
**Supported:** atdml (OCaml), atdgen (OCaml), atdpy (Python), atdts (TypeScript), atdj (Java), atds (Scala), atdd (Dart), atdcpp (C++)
87+
88+
Optional fields
89+
~~~~~~~~~~~~~~~
90+
91+
?field — absent JSON key <-> None
92+
93+
**Supported:** atdml (OCaml), atdgen (OCaml), atdpy (Python), atdts (TypeScript), atdj (Java), atds (Scala), atdd (Dart), atdcpp (C++)
94+
95+
Default-value fields
96+
~~~~~~~~~~~~~~~~~~~~
97+
98+
~field — absent JSON key uses a default
99+
100+
**Supported:** atdml (OCaml), atdgen (OCaml), atdpy (Python), atdts (TypeScript), atdj (Java), atds (Scala), atdd (Dart), atdcpp (C++)
101+
102+
Doc comments
103+
~~~~~~~~~~~~
104+
105+
<doc text="..."> -> language docstrings
106+
107+
**Supported:** atdml (OCaml), atdgen (OCaml), atdpy (Python), atdts (TypeScript), atdj (Java), atds (Scala)
108+
109+
**Not yet:** atdd (Dart), atdcpp (C++)
110+
111+
JSON field names
112+
~~~~~~~~~~~~~~~~
113+
114+
<json name="..."> on record fields
115+
116+
**Supported:** atdml (OCaml), atdgen (OCaml), atdpy (Python), atdts (TypeScript), atdj (Java), atds (Scala), atdd (Dart), atdcpp (C++)
117+
118+
JSON variant names
119+
~~~~~~~~~~~~~~~~~~
120+
121+
<json name="..."> on sum type constructors
122+
123+
**Supported:** atdml (OCaml), atdgen (OCaml), atdpy (Python), atdts (TypeScript), atdj (Java), atds (Scala), atdd (Dart), atdcpp (C++)
124+
125+
Assoc as JSON object
126+
~~~~~~~~~~~~~~~~~~~~
127+
128+
(string * v) list <json repr="object">
129+
130+
**Supported:** atdml (OCaml), atdgen (OCaml), atdpy (Python), atdts (TypeScript)
131+
132+
**Not yet:** atdj (Java), atds (Scala), atdd (Dart), atdcpp (C++)
133+
134+
JSON adapter
135+
~~~~~~~~~~~~
136+
137+
Custom pre/post-processing hooks
138+
139+
**Supported:** atdml (OCaml), atdgen (OCaml)
140+
141+
**Not yet:** atdpy (Python), atdts (TypeScript), atdj (Java), atds (Scala), atdd (Dart), atdcpp (C++)
142+
143+
Cross-file imports
144+
~~~~~~~~~~~~~~~~~~
145+
146+
from module import type1, type2
147+
148+
**Supported:** atdml (OCaml), atdpy (Python), atdts (TypeScript)
149+
150+
**Not yet:** atdj (Java), atds (Scala), atdd (Dart), atdcpp (C++)
151+
152+
**Not supported:** atdgen (OCaml)
153+
154+
Binary serialization
155+
~~~~~~~~~~~~~~~~~~~~
156+
157+
Biniou format: faster than JSON, field/constructor names encoded as low-collision hashes
158+
159+
**Supported:** atdgen (OCaml)
160+
161+
**Not supported:** atdml (OCaml), atdpy (Python), atdts (TypeScript), atdj (Java), atds (Scala), atdd (Dart), atdcpp (C++)
162+
163+
Open enumerations
164+
~~~~~~~~~~~~~~~~~
165+
166+
Unknown variants round-tripped as-is
167+
168+
**Supported:** atdgen (OCaml)
169+
170+
**Not yet:** atdpy (Python), atdts (TypeScript), atdj (Java), atds (Scala), atdd (Dart), atdcpp (C++)
171+
172+
**Not supported:** atdml (OCaml)
173+

‎internal/Makefile‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# Feature Support Matrix Generator
2+
# ==================================
3+
#
4+
# This directory contains a small OCaml program (src/main.ml) that generates
5+
# the feature support matrix page for the ATD documentation
6+
# (../doc/support-matrix.rst).
7+
#
8+
# Editing the table
9+
# -----------------
10+
# All data lives in src/main.ml as typed OCaml values (yes/no/planned per
11+
# feature per backend). This makes it easy to update individual cells, add
12+
# rows or columns, and keep the RST output consistently formatted — much
13+
# easier than editing a wide hand-crafted RST table directly.
14+
#
15+
# Regenerating the RST file
16+
# -------------------------
17+
# make build the program and overwrite ../doc/support-matrix.rst
18+
# make build build only, do not overwrite the RST file
19+
#
20+
# The generated file is committed to the repository so that the documentation
21+
# can be built without running OCaml.
22+
23+
DUNE := dune
24+
ROOT := ..
25+
OUT := $(ROOT)/doc/support-matrix.rst
26+
27+
.PHONY: all build
28+
29+
all: build
30+
cd $(ROOT) && $(DUNE) exec internal/src/main.exe > doc/support-matrix.rst
31+
32+
build:
33+
cd $(ROOT) && $(DUNE) build internal/src/main.exe

‎internal/src/dune‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
(executable
2+
(name main))

0 commit comments

Comments
 (0)