1 files changed, 44 insertions, 0 deletions
diff --git a/docs/layout-of-source-files.rst b/docs/layout-of-source-files.rst
new file mode 100644
index 00000000..445162f5
--- /dev/null
+++ b/docs/layout-of-source-files.rst
@@ -0,0 +1,44 @@
+********************************
+Layout of a Solidity Source File
+********************************
+
+Source files can contain an arbitrary number of contract definitions and include directives.
+
+.. index:: source file, ! import
+
+Importing other Source Files
+============================
+
+
+Other source files can be referenced using `import "filename";` and the symbols
+defined there will also be available in the current source file.
+
+.. warning::
+
+    Import will not work automatically for the commandline-compiler.
+    Furthermore, this system of importing other files is not completely fleshed out
+    yet, so please expect changes.
+
+The `browser-based compiler <https://chriseth.github.io/browser-solidity>`_
+has quite advanced support for multiple files and can even import files
+directly from github, by using e.g.
+```import "github.com/ethereum/dapp-bin/library/iterable_mapping.sol";```
+
+If you want to use multiple source files with the (commandline compiler)[../commandline-compiler/] solc,
+you have to specify all files you will use as arguments to solc,
+the compiler will not yet search your filesystem on its own.
+
+.. index:: ! comment, natspec
+
+Comments
+========
+
+Single-line comments (`//`) and multi-line comments (`/*...*/`) are possible.
+
+There are special types of comments called natspec comments
+(documentation yet to be written). These are introduced by 
+triple-slash comments (`///`) or using double asterisks (`/** ... */`).
+Right in front of function declarations or statements,
+you can use doxygen-style tags inside them to document functions, annotate conditions for formal
+verification and provide a **confirmation text** that is shown to users if they want to
+invoke a function.