Atdts: supporting <ts from ...> annotation

[koonwen]

PR checklist

• New code has tests to catch future regressions
• Documentation is up-to-date
• CHANGES.md is up-to-date

[koonwen]

@ygrek The feature is to be able to pass an OCaml module that is converted to the ts equivalent type or just have modularity to import types from another .atd file?

[ygrek]

this comment is now wrong
but also it is convenient to implement what this comment says - if there is no ts annot for from - use ocaml one. The reason this makes sense is because abstract without from gets generated as any in ts which is not very useful (I would consider actually turning it into error because from what i have seen 100% it is programmer mistake not intention)

[mjambon]

I disagree about reading <ocaml ...> annotations with atdts. TypeScript and OCaml should not know about each other. When there are similarities that are more or less universal, we should handle them in a language-neutral fashion (= no reference to other target languages).

See also #265 for a dedicated import syntax that turned out to be too complicated to implement in atdgen but is reasonable for the other target languages. The long-term solution I propose is to implement atdml (but unfortunately it would take me a solid 3 weeks to make something usable). See the comment I just left on my original PR attempt: #297 (comment)

[ygrek]

i believe this is documented in the general atd language documentation? (maybe mentioning in ts doc is useful but still should link/refer to the main doc)

[mjambon]

The annotation is <ts ...>, so it is specific to the TypeScript target and should be documented here.

[mjambon]

This should be <ocaml ts=...>. I would add a slightly longer note explaining what the feature is about.

[ygrek]

<ts from=..> ?

[koonwen]

Thanks for the comments @mjambon @ygrek, I've cleaned up the code by removing the references to ocaml. Also rewired the build system so that we don't need a cleanup-for-dune to remove filesystem state have for dune work as expected.

One thing that was surprising was that even though "ocaml" was not specified as a annot_schema in

atd/atdts/src/lib/Codegen.ml

Lines 22 to 34 in 5d00b9b

	let annot_schema_ts : Atd.Annot.schema_section =
	{
	section = "ts";
	fields = [
	Type_expr, "repr";
	Field, "default";
	Type_def, "from";
	Type_def, "t";
	]
	}
	let annot_schema : Atd.Annot.schema =
	annot_schema_ts :: Atd.Json.annot_schema_json

the initial validation pass when the .atd file is loaded doesn't raise an error.

It looks like the annotation validation pass only tries to check if the section was defined in annot_schema and allows the rest through which seems wrong? I.e. if annot_schema contains {section="ocaml"; fields=[]}, it would raise an error since no annotations are allowed for this section. But now if I don't provide the ocaml section, and try to annotate <ocaml from=...>, it passes.

[smondet]

LGTM modulo doc typos

[smondet]

s/OCaml/ATD/ ?

[smondet]

<ts

[koonwen]

Updated doc types, thanks @smondet. Merging