ocaml - 关于查找文档

Question

到目前为止，给谷歌搜索字符串，如

"ocaml" regex

"ocaml" hashtbl

等通常会为我提供我一直在寻找的文档。

一个值得注意的异常(exception)是

"ocaml" "String.Map"

通过这个搜索，我所能找到的(文档方面，即)是 String.map 的文档。 String 的功能模块(或者它是“包”？)。 (如果理解正确， String.Map 是一种数据结构，即其键的类型为 string 的映射，而不是函数。)

更强大的 Google 搜索规范，例如

"ocaml" intitle:"String.Map"

...找不到我要的文档。

对于 OCaml 中的特定标准项目，是否有一种不那么随意、更通用的方法来将文档归零？

(我在上面添加了“更通用”位，因为当人们想要搜索诸如 |> 、 >> 等非字母项目或某些非字母项目的项目时，使用搜索引擎是不切实际的功能对一个人的问题至关重要，例如当一个人想了解 'a 和 '_a 之间的区别时，或者当搜索区分大小写时，就像我当前的搜索一样。)

PS:我在明显的地方没有运气，例如

https://ocaml.org
http://caml.inria.fr/pub/docs/manual-ocaml/libref/
https://opam.ocaml.org/packages/

(这并不是说它不能通过其中一些链接“在某个地方”访问；我只是没有看到它。)

我做了一些绝望的猜测，并没有做得更好，比如

http://caml.inria.fr/pub/docs/manual-ocaml/libref/String.Map.html(状态码404)

编辑:这是另一个无法打开任何文档页面的搜索:

"ocaml" "of_alist_exn"

如果，据我了解， of_alist_exn是一些标准 OCaml 模块中的一个函数，然后我发现上面的搜索失败令人震惊。 (我得到了 18 次点击，但没有一个在我看来(基于 Google 结果列表中的可用信息)像文档页面。)

我从“被动”在线资源中学习了其他计算机语言的基础知识:教程和官方文档。而不是通过线性地从头到尾阅读本文档，而是通过搜索我想知道的内容。我发现以这种方式学习 OCaml 的基础知识也是不可能的。我想知道其他人是如何设法学习它的......我不得不假设它主要是通过口口相传(聊天室等)获得关键但没有记录的信息......

Answer 1

您需要了解 OCaml 标准库的一些背景知识。编译器附带了一个标准库，我们称之为 stdlib .这是很多年前写的很好但很薄的库。这就是为什么人们写了几个替代方案:Core , Batteries , extlib ，仅举几例。

OCaml 没有问题 stdlib , 但它非常小。但它可以被认为是一种优势，特别是如果你使用 OCaml 作为大学计算机科学类(class)的语言。但是如果你是一个专业的软件开发者，那么你很快就会发现它太短了。这就是 Janestreet 提供 OCaml Core 库的原因。非常显眼的图书馆，入口层比stdlib高很多.所以，我假设你正在使用这个库(我认为你做出了正确的选择，但这只是我的意见)。

核心库是标准库的覆盖。它使用不同的命名约定，并试图从标准库中隐藏定义。尽管许多仍然泄漏。除非您真的被迫这样做，否则您不应该将 vanilla 标准库与核心混合。在这种情况下，您应该明确使用 Caml模块，导出整个 stdlib .

现在，回到问题。 Core 库的官方文档可以通过简单的 ocaml core documentation 找到。查询，这将为您提供指向 official core documentation 的链接.如您所见，那里有很多模块。您应该从 Std 开始模块，这是一个导出他们认为应该导出的模块(参见 __init__.py )。在这个模块里面你可以找到String子模块。您甚至可能会看到，它从 Core_string 重新导出到您的命名空间中。模块(module String : Core_string)。这是您正在搜索的模块。你可以点击，微小的+符号也看模块里面，但是，这是丑点，只会有签名，没有文档。是的，我知道，这很糟糕，但稍后再说。因此，为了接收完整的文档，您需要点击 Core_string 模块，等等。因此，通过反复试验，我们找到了它。这个过程真的不友好，或者不如它可能的那么友好，但这只是因为没有人(原文如此)实际上以这种方式移动。有一个更好的办法。您应该掌握一些工具，才能真正提高 OCaml 的工作效率，它是 emacs , merlin , ocp-index , ocamlspot .当然，你可以替换为emacs对于 vim ， 如果你愿意。

因此，一旦您安装、配置并掌握了这些工具，您就可以在不离开您最喜欢的编辑器的情况下进行编码。首先，您可以直接从mli 中查找文档。文件。确实，mli是 OCaml 语言的一个杀戮特性。例如，如果我需要更新我对 String.strip 的知识函数，我只是将我的 emacs 指向 Core_string.mli模块，并阅读以下内容:

(* Warning: the following strip functions have copy-on-write semantics (i.e. they may
   return the same string passed in) *)

(** [lstrip ?drop s] returns a string with consecutive chars satisfying [drop] (by default
    white space, e.g. tabs, spaces, newlines, and carriage returns) stripped from the
    beginning of [s]. *)
val lstrip : ?drop:(char -> bool) -> t -> t

(** [rstrip ?drop s] returns a string with consecutive chars satisfying [drop] (by default
    white space, e.g. tabs, spaces, newlines, and carriage returns) stripped from the end
    of [s]. *)
val rstrip : ?drop:(char -> bool) -> t -> t

(** [strip ?drop s] returns a string with consecutive chars satisfying [drop] (by default
    white space, e.g. tabs, spaces, newlines, and carriage returns) stripped from the
    beginning and end of [s]. *)
val strip : ?drop:(char -> bool) -> t -> t

这是极好的文档，imo。还有一个警告，您不会在从此文件生成的文档中看到。

附言目前正在进行一项改进 OCaml 文档的工作。迟早，它会变得更好，更容易获得。但目前它有点骇人听闻。