Source files can (and should) be annotated with a so-called version pragma to reject
being compiled with future compiler versions that might introduce incompatible
changes. We try to keep such changes to an absolute minimum and especially
introduce changes in a way that changes in semantics will also require changes
in the syntax, but this is of course not always possible. Because of that, it is always
a good idea to read through the changelog at least for releases that contain
breaking changes, those releases will always have versions of the form
0.x.0 or x.0.0.

The version pragma is used as follows:

pragmasolidity^0.4.0;

Such a source file will not compile with a compiler earlier than version 0.4.0
and it will also not work on a compiler starting from version 0.5.0 (this
second condition is added by using ^). The idea behind this is that
there will be no breaking changes until version 0.5.0, so we can always
be sure that our code will compile the way we intended it to. We do not fix
the exact version of the compiler, so that bugfix releases are still possible.

It is possible to specify much more complex rules for the compiler version,
the expression follows those used by npm.

In the above, filename is always treated as a path with / as directory separator,
. as the current and .. as the parent directory. When . or .. is followed by a character except /,
it is not considered as the current or the parent directory.
All path names are treated as absolute paths unless they start with the current . or the parent directory ...

To import a file x from the same directory as the current file, use import"./x"asx;.
If you use import"x"asx; instead, a different file could be referenced
(in a global “include directory”).

It depends on the compiler (see below) how to actually resolve the paths.
In general, the directory hierarchy does not need to strictly map onto your local
filesystem, it can also map to resources discovered via e.g. ipfs, http or git.

When the compiler is invoked, it is not only possible to specify how to
discover the first element of a path, but it is possible to specify path prefix
remappings so that e.g. github.com/ethereum/dapp-bin/library is remapped to
/usr/local/dapp-bin/library and the compiler will read the files from there.
If multiple remappings can be applied, the one with the longest key is tried first. This
allows for a “fallback-remapping” with e.g. "" maps to
"/usr/local/include/solidity". Furthermore, these remappings can
depend on the context, which allows you to configure packages to
import e.g. different versions of a library of the same name.

solc:

For solc (the commandline compiler), these remappings are provided as
context:prefix=target arguments, where both the context: and the
=target parts are optional (where target defaults to prefix in that
case). All remapping values that are regular files are compiled (including
their dependencies). This mechanism is completely backwards-compatible (as long
as no filename contains = or :) and thus not a breaking change. All imports
in files in or below the directory context that import a file that
starts with prefix are redirected by replacing prefix by target.

So as an example, if you clone
github.com/ethereum/dapp-bin/ locally to /usr/local/dapp-bin, you can use
the following in your source file:

so that all imports in module2 point to the old version but imports
in module1 get the new version.

Note that solc only allows you to include files from certain directories:
They have to be in the directory (or subdirectory) of one of the explicitly
specified source files or in the directory (or subdirectory) of a remapping
target. If you want to allow direct absolute includes, just add the
remapping =/.

If there are multiple remappings that lead to a valid file, the remapping
with the longest common prefix is chosen.

Remix:

Remix
provides an automatic remapping for github and will also automatically retrieve
the file over the network:
You can import the iterable mapping by e.g.
import"github.com/ethereum/dapp-bin/library/iterable_mapping.sol"asit_mapping;.

Additionally, there is another type of comment called a natspec comment,
for which the documentation is not yet written. They are written with a
triple slash (///) or a double asterisk block(/**...*/) and
they should be used directly above function declarations or statements.
You can use Doxygen-style tags inside these comments to document
functions, annotate conditions for formal verification, and provide a
confirmation text which is shown to users when they attempt to invoke a
function.

In the following example we document the title of the contract, the explanation
for the two input parameters and two returned values.