在查找文档时

问题描述

到目前为止，给Google搜索字符串例如

So far, giving Google search strings such as

"ocaml" regex

"ocaml" hashtbl

等通常为我提供了我一直在寻找的文档.

etc. has usually gotten me the documentation I've been looking for.

一个值得注意的例外是

"ocaml" "String.Map"

通过此搜索，我所能找到的(就是从文档角度而言)是String模块的String.map function 的文档(或者是"package"?). . (如果理解正确，String.Map是一个数据结构，即其键的类型为string而不是函数的映射.)

With this search, all I can find (documentation-wise, that is), is documentation for the String.map function of the String module (or is it "package"?). (If understand correctly, String.Map is a data structure, namely a map whose keys have type string, rather than a function.)

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

Even more forceful Google search specs like

"ocaml" intitle:"String.Map"

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

...failed to find the documentation I'm after.

在OCaml中特定标准项的文档中，是否存在一种更少偶然性和更一般性的方法?

Is there a less haphazard, and more general, way to zero-in the documentation for a particular standard item in OCaml?

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

(I added the "and more general" bit above because using a search engine is not practical when one wants to search for non-alphabetic items such as |>, >>, etc., or for items where some non-alphabetic feature is critical to one's question, such as when one wants to learn about the difference between 'a and '_a, or when the search is case-sensitive, as my current search.)

PS:我对这些明显的地方没有运气，例如

PS: I had no luck with the obvious places, such as

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

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

(这并不是说它不能通过某些链接在某个地方"访问；我只是没有看到它.)

(This is not to say it's not "somewhere" accessible through some of those links; I'm just not seeing it.)

我在一些绝望的猜测中并没有表现得更好，例如

I did no better with some desperate guesses, like

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

http://caml.inria.fr/pub/docs/manual-ocaml/libref/String.Map.html (status code 404)

这是另一个未能打开任何文档页面的搜索:

Here's another search that fails to turn up any documentation page:

"ocaml" "of_alist_exn"

如果据我了解，of_alist_exn是 some 标准OCaml模块中的函数，那么令我震惊的是上述搜索失败. (我得到了18次点击，但没有一个(根据Google结果列表中的信息)对我来说像文档页面一样.)

If, as I understand it, of_alist_exn is a function in some standard OCaml module, then I find it shocking that the search above fails. (I get 18 hits, and not a single one of them looks to me (based on the info available in a Google results list) like a documentation page.)

我已经从被动"在线资源中学到了其他计算机语言的基础知识:教程和官方文档.而不是通过线性阅读这份文档，而是通过搜索我想知道的东西来了解.我发现无法以这种方式学习OCaml的基础知识.我不知道其他人如何设法学习它的...我不得不假设这主要是通过口碑(聊天室等)获得关键但未记录的信息...

I've learned the basics of other computer languages from "passive" online resources: tutorials and official documentation. And not by reading this documentation linearly cover-to-cover, but by searching for what I wanted to know as I needed to. I'm finding it impossible to learn even the basics of OCaml this way. I wonder how other people have managed to learn it... I have to assume it is mostly by getting crucial-but-undocumented information via word-of-mouth (chatrooms, etc.)...

推荐答案

您需要了解OCaml标准库的一些背景知识.编译器附带一个标准库，可将其命名为stdlib.这是一个很好的库，但是它非常瘦，它是很多年前编写的.这就是为什么人们写了几种选择的原因:Core，Batteries，extlib，仅举几例.

You need to know some background on OCaml standard libraries. There is a standard library that ships with the the compiler, lets call it stdlib. It is nice, but very thin library, that was written many years ago. That's why people wrote several alternatives: Core, Batteries, extlib, to name a few.

OCaml stdlib没什么问题，但是它很小.但这可以被认为是一种优势，特别是如果您将OCaml作为大学计算机科学课程的语言使用时.但是，如果您是专业软件开发人员，那么您很快就会发现它太短了.这就是为什么有来自Janestreet的OCaml Core库的原因.这是一个非常著名的图书馆，入口水平比stdlib高得多.因此，我假设您正在使用此库(并且我认为您做出了正确的选择，但这只是我的观点).

There is nothing wrong with OCaml stdlib, but it is very small. But it can be considered as an advantage, especially if you're using OCaml as language for a college level computer science course. But if you're a professional software develope, then you will soon find that it is too short. That's why there is an OCaml Core library from Janestreet. It is very prominent library, with much higher entrance level than stdlib. So, I'm assuming that you're using this library (and I think that you made a right choice, but this is only my opinion).

核心库是标准库的覆盖.它使用不同的命名约定，并且它们尝试从标准库中隐藏定义.尽管仍有许多泄漏.在真正被迫这么做之前，您不应该将香草标准库与核心混为一谈.在这种情况下，您应该显式使用Caml模块，该模块将导出整个stdlib.

Core library is an overlay over a standard library. It uses different naming conventions, and they try to hide definitions from the standard library. Although many still leaks. You shouldn't mix vanilla standard library with core, until you're really forced to. And in that case, you should explicitly use Caml module, that exports entire stdlib.

现在，回到问题所在.可以通过简单的ocaml core documentation查询找到Core库的官方文档，该查询将为您提供指向官方核心文档.您可能会看到那里有许多模块.您应该从 Std 模块开始是一个模块，可以导出他们认为应该导出的内容(参见__init__.py).在该模块内部，您可以找到String子模块.您甚至可能会看到，它已从Core_string模块(module String : Core_string)重新导出到您的命名空间中.这是您要搜索的模块.您可以单击，在模块内部也可以看到微小的+符号，但这有点丑陋，只有签名，没有文档.是的，我知道，这很糟糕，但是稍后再说.因此，为了获得完整的文档，您需要单击 Core_string 模块，等等.因此，通过反复试验，我们找到了它.这个过程确实不友好，或者不那么友好，但这仅仅是因为没有人(原文如此)实际上以这种方式行动.有一个更好的办法.您必须掌握一些工具，才能真正使用OCaml，它是emacs，merlin，ocp-index，ocamlspot.当然，您可以根据需要用emacs代替vim.

Now, back to the question. The official documentation for Core library can be found with a simple ocaml core documentation query, that will yield you a link to official core documentation. As you may see there're lots of modules there. You should start from Std module, this is a module that exports what they think that they should export (cf., __init__.py). Inside of this module you may find String submodule. You may even see, that it is reexported into your namespace from the Core_string module (module String : Core_string). This is the module you were searching for. You can click, the tiny + symbol too look inside the module, but, this is a point of ugliness, there will be only signatures, but no documentation. Yes, I know, it sucks, but later about this. So, in order to receive full documentation, you need to click on Core_string module, et voila. So, by trial and error we found it. The process is really not friendly, or not as friendly as it could be, but this is only because no one (sic) actually move in this way. There is a better way. There're tools, that you should master, to be really productive with OCaml, and it is emacs, merlin, ocp-index, ocamlspot. Of course, you can substitute emacs for vim, if you would like.

因此，一旦安装，配置并掌握了这些工具，就可以进行编码，而无需离开自己喜欢的编辑器.首先，您可以直接从mli文件中查找文档.实际上，mli是OCaml语言的主要功能.例如，如果需要刷新有关String.strip函数的知识，只需将emacs指向Core_string.mli模块，然后阅读以下内容:

So, once you have installed, configured and mastered these tools, you can do your coding without ever leaving your favorite editor. First of all, you can lookup for a documentation directly from the mli files. Indeed, mli is a killing feature of OCaml language. For example, if I need to refresh my knowledge on the String.strip function, I just point my emacs to the Core_string.mli module, and read these:

(* 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.还有警告，您不会在从该文件生成的文档中看到该警告.

It is excellent documentation, imo. Also there is warning, that you won't see in a documentation generated from this file.

P.S.正在进行改进OCaml文档的工作.迟早，它将变得更好，更容易使用.但是目前它有点骇人听闻.

P.S. There is a work in progress on making OCaml's documentation better. Sooner or later, it will become much better and accessible. But currently it is a little bit hackerish.

这篇关于在查找文档时的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持！