Indicate in documentation when something has to imported via require

[Tamnac]

Discussion

Currently some parts of the standard library must be imported via require x before usage. Whatever the reason for this, it leads to some usage problems:

1. It seems arbitrary which ones must be imported (there may be an internal reason, but it's not clear to a user)
2. It is not clear what is to imported (JSON is json but BigInt is just big?)

And it is never specified anywhere in the api documentation or crystal book, what is to be imported and why. In some cases it is shown in the example case near the top, in others such as BigInt not even that. In any case, simply having it in an example is very inexplicit.

In light of this I suggest:

1. Every class/module/whatever that needs an import should state so near the top
2. A section should be added to the crystal book and/or api homepage explaining how to use the standard library and that require may be needed sometimes

I am not sure about the style. The ruby docs have a heading dedicated to it (example) but perhaps a NOTE would be better.

[Tamnac]

I'm willing to take this up myself, it seems fairly easy for a beginner/outsider. I just need to know:

1. Does anyone know the full list of which items require importing, and what to import? Figuring it out for each one doesn't seem very productive.
2. Does anyone have any opinion on style? Otherwise I'll just go with whatever seems better to me

[straight-shoota]

So in general, the primary code examples should usually include a require statement when necessary. This is ensured by tests that we run on the code examples, so AFAIK it's pretty complete (when there are examples). BigInt has no examples in the type documentation. But there are examples for several methods, including the constructor which includes the require.

Note that subsequent examples usually don't repeat the require for brevity. I wouldn't object adding them everywhere, though to make the examples really self-contained.

https://github.com/crystal-lang/crystal/blob/master/src/prelude.cr is the standard prelude. It contains a list of require that are included by default in the core library. You never need to explicitly require anything that's also required from the prelude. Everything else needs to be required.

Regarding style, I don't have a clear suggestion. Maybe this could eventually be expressed as some kind of directive for the doc generator. But we don't have that yet, so we need to start with a free format. Probably just prose. Maybe we could use some kind of admonition style (e.g. NOTE: To use this class, you need to explicitly require it via `require "foo"` ).
Keeping the same format everywhere allows to easily transform it into something else later on.