Merge 8f7b681 into cb442aa

doc/driver.mld

@@ -700,7 +700,24 @@ let generate_all odocl_files =
 ]}
 
 
-Finally, we generate an index of all values, types, ... This index is meant to be consumed by search engines, to create their own index. It consists of a JSON array, containing entries with the name, full name, associated comment, link and anchor, and kind. Generating the index is done via [odoc compile-index], which create a json file.
+Finally, we generate an index of all values, types, ... This index is meant to be consumed by search engines, to create their own index. It is in json format. Generating the index is done via [odoc compile-index], which create a json file.
+
+Some more details about the json format:
+
+{ul
+  {- The whole file is a json array,}
+  {- each entry of the array correspond to an item to search. An entry is a json object, with the following fields:
+     {ul
+       {- ["id"], which is a string. It corresponds to the id of the entry, for instance: ["Stdlib.List.map"].}
+       {- ["doc"], which is a string. It corresponds to a "searchable" version of the docstring: one which is stripped from any html or specific markup. This is to avoid having too many results when searching ["class"], for instance.}
+       {- ["kind"] is a json object. It contains the fields:
+          {ul
+            {- ["kind"], a string telling the kind of the entry (type, value, module, standalone comment...)}
+            {- any information that is specific to it (for instance, a type has kind ["TypeDecl"] and also contains the constraints, manifest, and whether the type is private or not). For a comprehensive description of what information is available in this field, please refer to the source file: src/search/json_index/json_search.ml}}}
+       {- ["display"], which is a json object. It contains two fields:
+          {ul
+            {- ["url"], a string. It is the URL to the entry in the documentation, relative to the base of the documentation}
+            {- ["html"], also a string. It is the html odoc uses to display the entry in the search results.}}}}}}
 
 Search engines written in OCaml can also call the [Odoc_model.Fold.unit] and  [Odoc_model.Fold.page] function, in conjunction with [Odoc_search.Entry.entry_of_item] in order to get an OCaml value of each element to be indexed.