Update the documentation a bit.

README.md

@@ -1,29 +1,47 @@
-CppSharp is a binding tool that automatically generates either C#
-or C++/CLI wrappers around your C/C++ libraries by parsing headers.
+# CppSharp #
 
+## What does it do?
 
-Directory structure
--------------------
+This tool allows you to generate .NET bindings that wrap C/C++ code allowing interoperability with managed languages. This can be useful if you have an existing native codebase and want to add scripting support, or want to consume an existing native library in your managed code.
 
-Manual.md
-  Work-in-progress documentation for this tool.
+## Why reinvent the wheel?
 
-build/
-  Premake build scripts.
+There are not many automated binding tools around, the only real alternative is SWIG. So how is it different from SWIG?
 
-src/
-  Runtime
-    Helper runtime library to bridge the C++ standard library.
-  Bridge
-    Contains the needed classes to bridge the Clang parser to .NET.
-  Parser
-    C++/CLI based wrapper around the C++ Clang libraries.
-  Generator
-    The Clang-based binding generator.
+ * No need to generate a C layer to interop with C++.
+ * Based on an actual C++ parser (Clang) so very accurate.
+ * Understands C++ at the ABI (application binary interface) level
+ * Easily extensible semantics via user passes
+ * Strongly-typed customization APIs
+ * Can be used as a library
 
-tests/
-  Regression tests.
+## Can I use it yet?
 
-examples/
-  Hello
-    Small, Hello, World! example.
+It is being used to bind "real-world" complex codebases successfully, so give it a shot.
+
+Since C and C++ provide such a wide array of features I'm sure there's still tonnes of bugs and unsupported edge cases, but give and try and report any bugs you find and I'll try to fix them ASAP.
+
+## Getting started
+
+Since binary releases have not been provided yet, you will have to compile the project and dependencies manually (LLVM and Clang). 
+
+The documentation is still a work-in-progress, please see the following resources for more information:
+
+[User's Manual](docs/UsersManual.md)
+
+[Developer's Manual](docs/DevManual.md)
+
+
+## Similiar Tools
+
+* Sharppy - .NET bindings generator for unmanaged C++
+[https://code.google.com/p/sharppy/](https://code.google.com/p/sharppy/)
+
+* XInterop
+[http://xinterop.com/](http://xinterop.com/)
+
+* SWIG
+[http://www.swig.org/](http://www.swig.org/)
+
+* Cxxi
+[https://github.com/mono/cxxi/](https://github.com/mono/cxxi/)

docs/DevManual.md

@@ -0,0 +1,123 @@
+CppSharp Developers Manual
+
+1. Introduction
+===============
+
+How to compile
+--------------
+
+Requirements:
+  Windows
+  VS 2012
+  Up-to-date versions of Clang and LLVM (development versions).
+
+Since C++/CLI is used to interface with the native Clang libraries,
+for the moment you will need the Windows/VS platform to use this tool.
+
+How to use
+----------
+
+Since the generator was designed to be easily extensible, you can use it
+either as a library or as a command-line interface.
+
+### Library interface
+
+  With this approach you implement the ILibrary interface and customize
+  the options with C#. This is ideal since you get all the power of the
+  language to do the customizations you want and it is easy to integrate
+  in your IDE build system.
+
+### Command-line interface
+
+  With this one you call the executable with the right [command-line flags]
+  (Manual.md#command-line-flags) to generate the bindings code. You can still
+  integrate it in your IDE by using the pre-build command features. If you need
+  to customize the build you can pass the path to a compiled assembly with an
+  ILibrary implementation.
+
+2. Architecture
+===============
+
+
+## Driver
+
+The driver is responsible for setting up the needed context for the rest of
+the tool and for implementing the main logic for parsing the user-provided headers,
+processing the declarations adn then calling the language-specific generator to
+generate the bindings.
+
+
+## Parser
+
+Since writing bindings by hand is tedious and error-prone, an automated
+approach was preferred. The open-source Clang parser is used for the task,
+providing an AST (Abstract Syntax Tree) of the code, ready to be consumed
+by the generator.
+
+This is done in Parser.cpp, we walk the AST provided by Clang and mirror
+it in a .NET-friendly way. Most of this code is pretty straigtforward if
+you are familiar how Clang represents C++ code in AST nodes.
+
+Recommended Clang documentation: [http://clang.llvm.org/docs/InternalsManual.html](http://clang.llvm.org/docs/InternalsManual.html "Clang Internals")
+
+
+## Generator
+
+After parsing is done, some language-specific binding code needs to be generated.
+
+Different target languages provide different features, so each generator needs to
+process the declarations in certain ways to provide a good mapping to the target
+language.
+
+Aditionally some of it can be provided directly in the native source
+code, by annotating the declarations with custom attributes.
+ 
+## Runtime
+
+This implements the C++ implementation-specific behaviours that allow
+the target language to communicate with the native code. It will usually
+use an existing FFI that provides support for interacting with C code.
+
+It needs to know about the object layout, virtual tables, RTTI and
+exception low level details, so it can interoperate with the C++ code.
+
+3. ABI Internals
+===============
+
+Each ABI specifies the internal implementation-specific details of how
+C++ code works at the machine level, involving things like:
+
+ 1. Class Layout
+ 2. Symbol Naming
+ 3. Virtual tables
+ 4. Exceptions
+ 5. RTTI (Run-time Type Information)
+
+There are two major C++ ABIs currently in use:
+
+ 1. Microsoft (VC++ / Clang)
+ 2. Itanium (GCC / Clang)
+ 
+Each implementation differs in a lot of low level details, so we have to
+implement specific code for each one.
+
+The target runtime needs to support calling native methods and this is usually
+implemented with an FFI (foreign function interface) in the target language VM
+virtual machine). In .NET this is done via the P/Invoke system.
+
+
+4. Similiar Tools
+=================
+
+* Sharppy - .NET bindings generator for unmanaged C++
+[https://code.google.com/p/sharppy/](https://code.google.com/p/sharppy/)
+
+* XInterop
+[http://xinterop.com/](http://xinterop.com/)
+
+* SWIG
+[http://www.swig.org/](http://www.swig.org/)
+
+* Cxxi
+[https://github.com/mono/cxxi/](https://github.com/mono/cxxi/)
+

docs/UsersManual.md

@@ -1,15 +1,12 @@
-Clang/.NET code generation tool User's Manual
+CppSharp Users Manual
 
-1. Introduction
-===============
+# 1. Introduction
 
-What does it do?
-----------------
+## What does it do?
 
 This tool allows you to generate .NET bindings that wrap C/C++ code allowing interoperability with managed languages. This can be useful if you have an existing native codebase and want to add scripting support, or want to consume an existing native library in your managed code.
 
-Why reinvent the wheel?
------------------------
+## Why reinvent the wheel?
 
 There are not many automated binding tools around, the only real alternative is SWIG. So how is it different from SWIG?
 
@@ -20,60 +17,62 @@ There are not many automated binding tools around, the only real alternative is
  * Strongly-typed customization APIs
  * Can be used as a library
 
-2. Supported C/C++ language features
-====================================
+# 2. C/C++ language features
 
 In this section we will go through how the generator deals with each C / C++ feature.
 
-C/C++ Types
------------
+## C/C++ Types
 
 ### Fundamental types
 
 These are mapped to .NET types as follows:
 
-1. Integral types
-```
-char      -> System::Byte
-bool      -> System::Boolean
-short     -> System::Int16
-int, long -> System::Int32
-long long -> System::Int64
-```
-Signedness is also preserved in the conversions.
-
-2. Floating-point types
-```
-  float     -> System::Single
-  double    -> System::Double
-```
-
-3. Other types
-```
-  wchar_t   -> System::Char
-  void      -> System::Void
-```
+1. **Integral types**
+
+  char      **→** System::Byte
+  bool      **→** System::Boolean
+  short     **→** System::Int16
+  int, long **→** System::Int32
+  long long **→** System::Int64
+  
+  Note: Signedness is also preserved in the conversions.
+
+2. **Floating-point types**
+
+  float     **→** System::Single
+  double    **→** System::Double
+
+3. **Other types**
+
+  wchar_t   **→** System::Char
+  void      **→** System::Void
 
 ### Derived types
 
-1. Arrays are mapped to .NET CLR arrays.
+1. **Arrays**
+
+ These are mapped to .NET CLR arrays.
+
+2. **Function Pointers / Pointers to Members**
+
+ These are mapped to .NET CLR delegates.
 
-2. Function Pointers / Pointers to Members are mapped to .NET CLR delegates.
+3. **Pointers**
 
-3. Pointers are mapped to .NET CLR references unless:
-```
-  void*        -> System::IntPtr
-  const char*  -> System::String
-```
+ These are mapped to .NET CLR references unless:
 
-4. References are mapped to .NET CLR references just like pointers.
+  void*        **→** System::IntPtr
+  const char*  **→** System::String
 
-### Typedefs
+4. **References**
+
+ References are mapped to .NET CLR references just like pointers.
+
+## Typedefs
 
 We do not preserve type definitions since .NET and its main language C# do not have the concept of type aliases like C/C++. There is an exception in the case of a typedef'd function (pointer) declaration. In this case generate a .NET delegate with the name of the typedef.
 
-Enums
------
+## Enums
 
 C/C++ enums are translated automatically to .NET enumerations.
 
@@ -81,14 +80,13 @@ Special cases to be aware of:
 
 1. Anonymous enums
 
-C and C++ enums (this does not apply to the new C++11 strongly typed enums) do not introduce their own scope. This means the enumerated values will leak into an outer context, like a class or a namespace. When this is detected, the generator tries to map to an outer enclosing context and generate a new name.
+ C and C++ enums (this does not apply to the new C++11 strongly typed enums) do not introduce their own scope. This means the enumerated values will leak into an outer context, like a class or a namespace. When this is detected, the generator tries to map to an outer enclosing context and generate a new name.
 
 2. Flags / Bitfields
  
-Some enumerations represent bitfield patterns. The generator tries to check for this with some heuristics. If there are enough values in the enum to make a good guess, we apply the [Flags] .NET attribute to the wrapper enum.
+ Some enumerations represent bitfield patterns. The generator tries to check for this with some heuristics. If there are enough values in the enum to make a good guess, we apply the [Flags] .NET attribute to the wrapper enum.
 
-Functions
----------
+## Functions
 
 Since global scope functions are not supported in C# (though they are available in the CLR) they are mapped as a static function in a class, to be consumable by any CLS-compliant language.
 
@@ -114,8 +112,7 @@ Special cases to be aware of:
 
   We do not try to wrap arguments default values yet. This is desired but needs more research since potentially all C++ constant expressions can be used as default arguments, though it would be pretty simple to add this for the common case of null constants.
 
-Classes / Structs
------------------
+## Classes / Structs
 
 Unlike .NET, in which there is an explicit differentiation of the allocation semantics of the type in the form of classes (reference types) and structs (value types), in C++ both classes and structs are identical and can be used in both heap (malloc/new) and automatic (stack) allocations.
 
@@ -147,37 +144,35 @@ TODO: Convert C++ conversion operators to .NET conversion operators.
 
 ### Inheritance
 
-C++ supports different types of implementation inheritance:
+C++ supports implementation inheritance of multiple types. This is incompatible with .NET which supports only single implementation inheritance (but multiple interface inheritance).
 
 1. Single inheritance
 
-This is the simplest case 
+ This is the simplest case and we can map the inheritance directly.
 
 2. Multiple inheritance
 
-
+ In this case we can only map one class directly. The others can be mapped as interfaces if they only provide pure virtual methods. Otherwise the best we can do is provide some conversion operators in .NET to get access to them.
 
 3. Virtual inheritance
 
-This is not supported for now.
+ This is not supported for now.
 
-### Bitfields
+## Bitfields
 
 This feature is not supported yet.
 
-### Unions
+## Unions
  
 This feature is not supported yet.
 
-Templates
----------
+## Templates
 
-Template types are supported at the moment 
+Template parsing is supported and you can type map them to other types.
 
-At the moment, template specializations are not exported yet. 
+TODO: Also export explicit template type specializations.
 
-Preprocessor defines
---------------------
+## Preprocessor defines
 
 Since C preprocessor definitions can be used for very different purposes, we can only do so much when converting them to managed code.
 
@@ -197,37 +192,49 @@ Since C preprocessor definitions can be used for very different purposes, we can
  
  This case is not supported and probably never will.
 
-Comments
---------
+## Comments
 
 Doxygen-style C++ comments are translated to .NET XML-style comments. This feature is experimental and limited to what Doxygen directives the upstream Clang parser supports.
 
-3. Customization
-================
+### Exceptions
+
+This feature is not supported yet.
+
+## RTTI
+
+This feature is not supported yet.
+
+# 3. Customization
 
 The generator provides various ways to customize the generation process.
 
-Type Maps
----------
+## Type Maps
 
 If all you need to do is customize what gets generated for a type, then you can use the type maps feature. This lets you hook into the process for a specific type pattern.
 
-### Standard library support
+## Standard library support
 
 The generator provides type maps for the most common C/C++ standard library types:
 
 * String
 
+ The native C++ string type, std::string, is mapped automatically to .NET strings.
+
 * Containers
 
 1. Vector
 
+ TODO: This is not supported yet.
+
 2. Map
 
+ TODO: This is not supported yet.
+
 3. Set
 
-Passes
-------
+ TODO: This is not supported yet.
+
+## Passes
 
 If you need more control then you can write your own pass. Passes have full access to the parsed AST (Abstract Syntax Tree) so you can modify the entire structure and declaration data of the source code. This is very powerful and should allow you to pretty much do anything you want.
 
@@ -264,47 +271,14 @@ This pass introduces a property that calls the native C/C++ getter and setter fu
 
 Some internal functionalities are also implemented as passes like checking for invalid declaration names or resolving incomplete declarations. Please check the developer manual for more information about these.
 
-4. Targets
-==========
+# 4. Targets
 
 The backend of the generator is abstracted and it can target different .NET binding technologies:
 
-1. C++/CLI
-
-
-
-2. C# (P/Invoke)
-
-
-
-
-5. Command Line Reference
-=========================
-
-When you launch the executable with no options, you are presented with the following options:
-
-```
-Usage: Generator.exe [options]+ headers
-Generates .NET bindings from C/C++ header files.
-
-Options:
-  -D, --defines=VALUE
-  -I, --include=VALUE
-      --ns, --namespace=VALUE
-
-  -o, --outdir=VALUE
-      --debug
-      --lib, --library=VALUE
-  -t, --template=VALUE
-  -a, --assembly=VALUE
-  -v, --verbose
-  -h, -?, --help
-```
-
-  * -D: Defines preprocessor macros (equivalent to #define).
+## C++/CLI
 
-  * -I: Specifies additional include directories.
+ This is the most developed target at the moment. It generates C++/CLI source code that should be compiled with a C++/CLI compiler and linked with the original library. Since all the hard logic is in the compiler this generator is relatively simple and easy to debug.
 
-  * -o: Specifies the base output directory for generated files.
+## C# (P/Invoke)
 
-  * -a: Specifies the .NET assembly that should be used as a driver.
+ This was the original backend and generates C# source code that calls back into native by using P/Invoke interop technology. It has bitrotted a bit lately but maybe it should be brought back, at least to the level of binding C and simple C++ libraries. It is much simpler to debug C# managed code than it is to debug the C++/CLI compiler. Even if C++/CLI ends up being the superior technology for C++ interop, this would be very useful for binding C libraries to .NET.