Update docs

Author: cannorin

CHANGELOG.md

@@ -8,7 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Ts2ocaml now emits builder function `[@js.builder]` for POJO interfaces.
 
 ## [1.4.0-beta.3] - 2022-01-17
-- Add option `--human-readable-anonymous-interface-names` (or `--readable-names`) to try to use more readable names instead of `AnonymousInterfaceN`.
+- Add an option `--readable-names` to try to use more readable names instead of `AnonymousInterfaceN`.
 
 ## [1.4.0-beta.2] - 2022-01-17
 - Fix a bug which prevented ts2ocaml from generating anonymous interfaces when used with --simplify=named-interface-value

build.fsx

@@ -143,7 +143,7 @@ module Test =
          "safe", !! "node_modules/@types/yargs-parser/index.d.ts", [];
          "safe", !! "node_modules/@types/yargs/index.d.ts", ["--rec-module=off"];
 
-         "minimal", !! "node_modules/@types/vscode/index.d.ts", ["--safe-arity=full "];
+         "minimal", !! "node_modules/@types/vscode/index.d.ts", ["--safe-arity=full"; "--readable-names"];
       ]
 
       for preset, package, additionalOptions in packages do

docs/js_of_ocaml.md

@@ -918,3 +918,52 @@ let _ = Foo.someMethod (foo ()) 42.0
 ```
 
 A notable example is the `document` variable in DOM (https://github.com/microsoft/TypeScript/blob/main/lib/lib.dom.d.ts).
+
+
+## `--try-readable-names`
+
+Try to use more readable names instead of `AnonymousInterfaceN`.
+
+* If the anonymous interface is an argument of a function, the name of the argument will be used.
+```typescript
+declare function foo(person: { name: string; age: number }) : void;
+```
+
+```ocaml
+module PersonN : sig
+  type t
+  val get_name: t -> string
+  val set_name: t -> string -> unit
+  val get_age:  t -> float
+  val set_age:  t -> float -> unit
+
+  val create: name:string -> age:float -> unit -> t
+end
+
+val foo: person:PersonN.t -> unit
+```
+
+* If the anonymous interface is the type of a field or the return type of a function, the name of the field/function will be used.
+```typescript
+declare const foo: { name: string };
+
+declare function bar(age: number) : { age: number };
+```
+
+```ocaml
+module FooN : sig
+  type t
+  val get_name: t -> string
+  ...
+end
+
+val get_foo: unit -> FooN.t
+
+module BarN : sig
+  type t
+  val get_age: t -> float
+  ...
+end
+
+val bar: float -> BarN.t
+```

src/Targets/JsOfOCaml/Common.fs

@@ -103,7 +103,7 @@ type Options =
   abstract recModule: RecModule with get, set
   abstract safeArity: FeatureFlag with get, set
   abstract simplify: Simplify list with get, set
-  abstract humanReadableAnonymousInterfaceNames: bool with get, set
+  abstract readableNames: bool with get, set
 
 module Options =
   open Fable.Core.JsInterop
@@ -247,11 +247,10 @@ module Options =
           sprintf "Turn on simplification features. Available features: %s"
                   (Simplify.Values |> Array.map string |> String.concat ", "))
       .addFlag(
-        "human-readable-anonymous-interface-names",
-        (fun (o: Options) -> o.humanReadableAnonymousInterfaceNames),
+        "readable-names",
+        (fun (o: Options) -> o.readableNames),
         descr="Try to use more readable names instead of AnonymousInterfaceN.",
-        defaultValue = false,
-        alias="readable-names"
+        defaultValue = false
       )
 
       .middleware(!^validate)

src/Targets/JsOfOCaml/Writer.fs

@@ -88,7 +88,7 @@ let literalToIdentifier (ctx: Context) (l: Literal) : text =
 
 let anonymousInterfaceModuleName (ctx: Context) (info: AnonymousInterfaceInfo) =
   match info.origin.valueName, info.origin.argName with
-  | _, Some s | Some s, None when ctx.options.humanReadableAnonymousInterfaceNames ->
+  | _, Some s | Some s, None when ctx.options.readableNames ->
     sprintf "%s%d" (Naming.toCase Naming.PascalCase s) info.id
   | _, _ ->
     sprintf "AnonymousInterface%d" info.id