add preliminary versions of documentation

.gitignore

@@ -0,0 +1,19 @@
+# ignore all ZIP files
+
+*.zip
+
+
+
+# ignore stcube_repository folder
+
+stcube_repository/*
+
+# except CMakeLists file
+
+!stcube_repository/CMakeLists.txt
+
+
+
+# ignore build folder
+
+build/*

CODE_KEEPERS.md

@@ -0,0 +1,19 @@
+The following is a list of keepers for different areas of the **nano Framework** code. 
+Each of the keepers is responsible for ensuring that changes in their areas 
+are reviewed, either by themselves or by someone they designate, in 
+addition to being the final word for the architecture and content of an area.
+
+List sorted by name and the fields are Name (N), GitHub user account (G), 
+Area (A).
+
+Note: If you don't find the area in the below list, or you have a general 
+question, send a message to Stanislav Šimíček (@cw2) or José Simões
+(@josesimoes). They can ensure that the question gets forwarded to the
+right person or answer it themselves.  
+
+| Name | GitHub user | Area |
+| --- | --- | --- |
+| José Simões | @josesimoes | Native code build, VS Code Debug and CMake |
+| Stanislav Šimíček | @cw2 | Debug protocol, nano Framework Interpreter |
+
+This list is incomplete, if you need to find other keepers please ping the team to get them filled in.

docs/README.md

@@ -1,6 +1,30 @@
-# Introduction to nano Framework Interpreter
+# Documents Index
 
-## Architecture
+This repo includes several documents that explain both high-level and low-level concepts about the **nano Framework**. These are very useful for contributors, to get context that can be very difficult to acquire from just reading code.
 
-## Developer Guide
+## Intro to **nano Framework**
 
+**nano Framework** is ?????????????????. It targets ARM Cortex M architectures and can be ported to multiple platforms.
+
+## Getting Started
+
+<!--- [??????](https://?????)-->
+
+## Project Documentation
+
+- [Developer Guide](project-documentation/developer-guide.md)
+- [Project priorities](project-documentation/project-priorities.md)
+- [Contributing to **nano Framework**](project-documentation/contributing.md)
+- [Contributing Workflow](project-documentation/contributing-workflow.md)
+
+## Build **nano Framework**
+
+- [Building **nano Framework**](building/build-instructions.md)
+
+## Testing and Debugging **nano Framework**
+
+- [Debugging **nano Framework** with VS Code](building/vscode-debug-instructions.md)
+
+## CMake Documentation
+
+- [CMake configuration files](cmake-documentation/README.md)

docs/building/vscode-debug-instructions.md

@@ -0,0 +1,56 @@
+# Instructions for debuging **nano Framework** native code in VS Code
+
+## Table of contents ##
+
+- [Prerequisites](#Prerequisites)
+- [Preparation](#Preparation)
+- [Launch the debug session](#LaunchTheDebugSession)
+
+**About this document**
+
+This document describes how to debug **nano Framework** native code using VS Code.
+
+<a name="Prerequisites"></a>
+# Prerequisites
+
+You'll need:
+- [GNU ARM Embedded Toolchain](https://developer.arm.com/open-source/gnu-toolchain/gnu-rm/downloads)
+- [Visual Studio Code](http://code.visualstudio.com/)
+- [C/C++ extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools)
+- OpenOCD (any working distribution will work, follow some suggestions)
+    - [Freddie Chopin OpenOCD (development)](http://www.freddiechopin.info/en/download/category/10-openocd-dev)
+    - [OpenOCD – Open On-Chip Debugger](https://sourceforge.net/projects/openocd/)
+    - [GNU ARM Eclipse OpenOCD](https://github.com/gnuarmeclipse/openocds)
+
+
+<a name="Preparation"></a>
+# Preparation
+
+You'll need a binary image with debug information to be loaded in the SoC or MCU.
+Assuming you are using VS Code to launch your builds, you'll have this image ready to be loaded in the MCU.
+(see [Build instructions documentation](build-instructions.md))
+
+In order to launch the debug session you'll need to tweak the *launch.json* file, located in the .vscode folder.
+Here's what you probably need to change in order to adapt this file to your setup.
+- miDebuggerPath: full path to the gdb executable (this one is inside the GCC toolchain folder)
+- program: full path to the .hex or .bin output file that results from a successful build
+- setupCommands (third ‘text’ entry): full path to the final image (same as above)
+- setupCommands (fourth ‘text’ entry): the same as the program entry above
+- debugServerPath: full path to the OpenOCD executable
+- debugServerArgs: full path to the scripts directory on the OpenOCD installation AND the appropriate .cfg files for the interface and the board.
+
+
+<a name="LaunchTheDebugSession"></a>
+# Launch the debug session
+
+Using VS Code menu View > Debug, clicking on the debug icon on the left hand toolbar or hitting the CTRL+SHIT+D shortcut you’ll reach the debug view. There you’ll find the launch configurations for debug that we’ve setup above (see the drop down at the top) and the familiar green play button (or F5 if you prefer).
+
+When a debug session is active you can find a lot of familiar stuff:
+- debug toolbar with the usual operations (pause, step over, into, out, restart and stop)
+- variables list
+- call stack that you can use to navigate up and down
+- breakpoint list to manage those
+- watch expressions
+- support for ‘mouse over’ a variable which will display a context with the variable content
+- ability to set/remove breakpoints by clicking near the line number
+- other handy tools and options using the right click on the various objects

docs/coding-guidelines/cs-coding-style.md

@@ -0,0 +1,126 @@
+# C# Coding Style
+
+For non code files (xml etc) our current best guidance is consistency. When editing files, keep new code and changes consistent with the style in the files. For new files, it should conform to the style for that component. Last, if there's a completely new component, anything that is reasonably broadly accepted is fine.
+
+The general rule we follow is "use Visual Studio defaults".
+
+1. We use [Allman style](http://en.wikipedia.org/wiki/Indent_style#Allman_style) braces, where each brace begins on a new line. A single line statement block can go without braces but the block must be properly indented on its own line and it must not be nested in other statement blocks that use braces. 
+2. We use four spaces of indentation (no tabs).
+3. We use `_camelCase` for internal and private fields and use `readonly` where possible. Prefix instance fields with `_`, static fields with `s_` and thread static fields with `t_`. When used on static fields, `readonly` should come after `static` (i.e. `static readonly` not `readonly static`).
+4. We avoid `this.` unless absolutely necessary. 
+5. We always specify the visibility, even if it's the default (i.e.
+   `private string _foo` not `string _foo`). Visibility should be the first modifier (i.e. 
+   `public abstract` not `abstract public`).
+6. Namespace imports should be specified at the top of the file, *outside* of
+   `namespace` declarations and should be sorted alphabetically.
+7. Avoid more than one empty line at any time. For example, do not have two
+   blank lines between members of a type.
+8. Avoid spurious free spaces.
+   For example avoid `if (someVar == 0)...`, where the dots mark the spurious free spaces.
+   Consider enabling "View White Space (Ctrl+E, S)" if using Visual Studio, to aid detection.
+9. If a file happens to differ in style from these guidelines (e.g. private members are named `m_member`
+   rather than `_member`), the existing style in that file takes precedence.
+10. We only use `var` when it's obvious what the variable type is (i.e. `var stream = new FileStream(...)` not `var stream = OpenStandardInput()`).
+11. We use language keywords instead of BCL types (i.e. `int, string, float` instead of `Int32, String, Single`, etc) for both type references as well as method calls (i.e. `int.Parse` instead of `Int32.Parse`).
+12. We use PascalCasing to name all our constant local variables and fields. The only exception is for interop code where the constant value should exactly match the name and value of the code you are calling via interop.
+13. We use ```nameof(...)``` instead of ```"..."``` whenever possible and relevant.
+14. Fields should be specified at the top within type declarations.
+
+We have provided a Visual Studio 2013 vssettings file (`nfcore.vssettings`) at the root of the repository, enabling C# auto-formatting conforming to the above guidelines. Note that rules 7 and 8 are not covered by the vssettings, since these are not rules currently supported by VS formatting.
+
+### Example File:
+
+``ObservableLinkedList`1.cs:``
+
+```C#
+using System;
+using System.Collections;
+using System.Collections.Generic;
+using System.Collections.Specialized;
+using System.ComponentModel;
+using System.Diagnostics;
+using Microsoft.Win32;
+
+namespace System.Collections.Generic
+{
+    public partial class ObservableLinkedList<T> : INotifyCollectionChanged, INotifyPropertyChanged
+    {
+        private ObservableLinkedListNode<T> _head;
+        private int _count;
+
+        public ObservableLinkedList(IEnumerable<T> items)
+        {
+            if (items == null)
+                throw new ArgumentNullException(nameof(items));
+
+            foreach (T item in items)
+            {
+                AddLast(item);
+            }
+        }
+
+        public event NotifyCollectionChangedEventHandler CollectionChanged;
+
+        public int Count
+        {
+            get { return _count; }
+        }
+
+        public ObservableLinkedListNode AddLast(T value) 
+        {
+            var newNode = new LinkedListNode<T>(this, value);
+
+            InsertNodeBefore(_head, node);
+        }
+
+        protected virtual void OnCollectionChanged(NotifyCollectionChangedEventArgs e)
+        {
+            NotifyCollectionChangedEventHandler handler = CollectionChanged;
+            if (handler != null)
+            {
+                handler(this, e);
+            }
+        }
+
+        private void InsertNodeBefore(LinkedListNode<T> node, LinkedListNode<T> newNode)
+        {
+           ...
+        }
+
+        ...
+    }
+}
+```
+
+``ObservableLinkedList`1.ObservableLinkedListNode.cs:``
+
+```C#
+using System;
+
+namespace System.Collections.Generics
+{
+    partial class ObservableLinkedList<T>
+    {
+        public class ObservableLinkedListNode
+        {
+            private readonly ObservableLinkedList<T> _parent;
+            private readonly T _value;
+
+            internal ObservableLinkedListNode(ObservableLinkedList<T> parent, T value)
+            {
+                Debug.Assert(parent != null);
+
+                _parent = parent;
+                _value = value;
+            }
+
+            public T Value
+            {
+               get { return _value; }
+            }
+        }
+
+        ...
+    }
+}
+```

docs/coding-guidelines/cxx-coding-style.md

@@ -0,0 +1,26 @@
+# C/C++ Coding Style
+
+For C/C++ files (*.c, *.cpp and *.h), we use clang-format (version 3.6+) to ensure code styling. 
+
+## Using Visual Studio Code
+
+If you are using Visual Studio Code we suggest that you install the [Clang-Format extension](https://marketplace.visualstudio.com/items?itemName=xaver.clang-format).
+To have this extension working you need to have the clang-format.exe installed in your system.
+
+LLVM.org doesn't provide a separate installer for this tool so follows a quick and dirty way of getting it.
+1. Install the Clang-Format extension.
+2. Install the Visual Studio plugin (as described bellow) and **DON'T** close the install window before opening the install log.
+3. After a succesfull install of the plugin, scroll down the install log until you find the path where it was installed.
+4. Copy that path and edit your VS Code user settings.
+5. Add to the end of the setting collection the following:
+```
+"clang-format.executable" : "C:/Users/nnnnnnnnn/AppData/Local/Microsoft/VisualStudio/14.0/Extensions/yyyyyy.zzzz/clang-format.exe"
+```
+You might have something different in your setup. 
+Just remeber the following: add that setting, the path that you've copied before, change it to have forward slashes and add the **clang-format.exe** at the end.
+
+After following the above steps suceesfully you can now right click on any C, C++ or H file and hit 'Format Document'. The VS Code extension will take care that the document is properly formated according to the coding style guidelines.
+
+## Using Visual Studio
+
+If you are using Visual Studio we suggest that you install the [clang-format plugin for Visual Studio](http://llvm.org/builds/).

docs/project-documentation/contributing-workflow.md

@@ -0,0 +1,92 @@
+# Contribution Workflow
+
+You can contribute to **nano Framework** with issues and PRs. Simply filing issues for problems you encounter is a great way to contribute. Contributing implementations is greatly appreciated.
+
+## Getting Started
+
+If you are looking at getting your feet wet with some simple (but still beneficial) changes, check out _up-for-grabs_ issues on the [**nano Framework** Interpreter](https://github.com/nano-framework/nf-interpreter/labels/up-for-grabs) repo. 
+
+For new ideas, please always start with an issue before starting development of an implementation. See [project priorities](project-priorities.md) to understand the team's approach to engagement on general improvements to the product. Use [CODE_KEEPERS.md](CODE_KEEPERS.md) to find relevant maintainers and @ mention them to ask for feedback on your issue.
+
+You do not need to file an issue for trivial changes (e.g. typo fixes). Just create a PR for those changes.
+
+## Making a change
+
+Make a quality change. Consider and document (preferably with tests) as many usage scenarios as you can to ensure that your change will work correctly in the miriad of ways it might get used.
+
+There are several issues to keep in mind when making a change.
+
+<!--Managed Code Compatibility
+--------------------------
+Please review [Breaking Changes](https://github.com/dotnet/corefx/blob/master/Documentation/coding-guidelines/breaking-changes.md) before making changes to managed code. Please pay the most attention to changes that affect the [Public Contract](https://github.com/dotnet/corefx/blob/master/Documentation/coding-guidelines/breaking-changes.md#bucket-1-public-contract).-->
+
+## Typos
+Typos are embarrassing! We will accept most PRs that fix typos. In order to make it easier to review your PR, please focus on a given component with your fixes or on one type of typo across the entire repository. If it's going to take >30 mins to review your PR, then we will probably ask you to chunk it up.
+
+## Coding Style Changes
+
+We would like to have **nano Framework** in full conformance with the style guidelines described here [C/C++ Coding Style](../coding-guidelines/cxx-coding-style.md) and here [C# Coding Style](../coding-guidelines/cs-coding-style.md). We plan to do that with tooling, in a holistic way. In the meantime, please:
+
+* **DO NOT** send PRs for style changes. 
+* **DO** give priority to the current style of the project or file you're changing even if it diverges from the general guidelines.
+
+## Commit Messages
+
+Please format commit messages as follows (based on this [excellent post](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)):
+
+```
+Summarize change in 50 characters or less
+
+Provide more detail after the first line. Leave one blank line below the
+summary and wrap all lines at 72 characters or less.
+
+If the change fixes an issue, leave another blank line after the final
+paragraph and indicate which issue is fixed in the specific format
+below.
+
+Fix #42
+```
+
+Also do your best to factor commits appropriately, i.e not too large with unrelated
+things in the same commit, and not too small with the same small change applied N
+times in N different commits. If there was some accidental reformatting or whitespace
+changes during the course of your commits, please rebase them away before submitting
+the PR.
+
+## PR Feedback
+
+**nano Framework** team and community members will provide feedback on your change. Community feedback is highly valued. You will often see the absence of team feedback if the community has already provided good review feedback. 
+
+1 or more **nano Framework** team members will review every PR prior to merge. They will often reply with "LGTM, modulo comments". That means that the PR will be merged once the feedback is resolved. "LGTM" == "looks good to me".
+
+There are lots of thoughts and [approaches](https://github.com/antlr/antlr4-cpp/blob/master/CONTRIBUTING.md#emoji) for how to efficiently discuss changes. It is best to be clear and explicit with your feedback. Please be patient with people who might not understand the finer details about your approach to feedback.
+
+**nano Framework** project uses many labels for categorizing issues and pull requests. Check [here](labels.md) the full list.
+
+## Suggested Workflow
+
+We use and recommend the following workflow:
+
+1. Create an issue for your work. 
+  - You can skip this step for trivial changes.
+  - Reuse an existing issue on the topic, if there is one.
+  - Use [CODE_KEEPERS.md](CODE_KEEPERS.md) to find relevant maintainers and @ mention them to ask for feedback on your issue.
+  - Get agreement from the team and the community that your proposed change is a good one.
+  - If your change adds a new API, follow the [API Review Process](api-review-process.md). 
+  - Clearly state that you are going to take on implementing it, if that's the case. You can request that the issue be assigned to you. Note: The issue filer and the implementer don't have to be the same person.
+2. Create a personal fork of the repository on GitHub (if you don't already have one).
+3. Create a branch off of **dev** (`git checkout -b mybranch`). 
+  - Name the branch so that it clearly communicates your intentions, such as issue-123 or githubhandle-issue. 
+  - Branches are useful since they isolate your changes from incoming changes from upstream. They also enable you to create multiple PRs from the same fork.
+4. Make and commit your changes.
+  - Please follow our [Commit Messages](contributing-workflow.md#commit-messages) guidance.
+5. Add new tests corresponding to your change, if applicable.
+6. Build the repository with your changes.
+  - Make sure that the builds are clean.
+  - Make sure that the tests are all passing, including your new tests.
+7. Create a pull request (PR) against the upstream repository's **dev** branch.
+  - Push your changes to your fork on GitHub (if you haven't already).
+
+Note: It is OK for your PR to include a large number of commits. Once your change is accepted, you will be asked to squash your commits into one or some appropriately small number of commits before your PR is merged.
+
+Note: It is OK to create your PR as "[WIP]" on the upstream repo before the implementation is done. This can be useful if you'd like to start the feedback process concurrent with your implementation. State that this is the case in the initial PR comment.