update docs

Author: roman_yakovenko

docs/msvc/msvc.rest

@@ -1,88 +1,110 @@
-=========================
-MS Visual Studio backends
-=========================
+==========================
+MS Visual Studio back-ends
+==========================
 
 .. contents:: Table of contents
 
-----------------------------------------
-Why we need other than GCC-XML backends?
-----------------------------------------
+-----------------------------------------
+Why we need other than GCC-XML back-ends?
+-----------------------------------------
 
 It is not a secret, that Windows is not a native environment for GCC. There are 
 cases, that it cant compile the code, "produced" for other compilers. On Windows, 
 if you want to use `GCC-XML`_, you should treat it as another compiler and adopt 
 your source code. Sometimes, changing the source code is not an option and different
 solution is needed.
 
-Recently, I started to work on another back-end for `pygccxml`_, based on free tools,
-available and freely redistributable with MS Visual Studio:
+--------
+The idea
+--------
 
-* PDB - program database. A .pdb files hold debugging information about your 
-  program. In other words, it contains information about every type and function 
-  you use. 
-* BSC - browse source code. A .bsc file is a comprehensive database that contains 
-  information about a program's symbols, including symbol references, 
-  function calltrees, and definition tables. 
+The idea is the same as with `GCC-XML`_ - don't write custom C++ parser, but use
+the compiler to extract the information.
 
-Both .pdb and .bsc files contain valuable information about your source code. 
-I guess, you will be surprised how much information it is possible to extract 
-from them.
+During the build process, MS Visual Studio generates few files, which contain 
+source code "description":
 
-----------------------------
-How it works?
-----------------------------
+* .pdb file. A "program database" file holds debugging information about your 
+  program. It is generated automaticly during "Debug" builds.
 
-Microsoft provides API for extracting information from the files:
+* .bsc file. A "browse source code" file is a comprehensive database that contains 
+  information about a program's symbols, including symbol references, function 
+  calltrees, and definition tables. .bsc file is not generated by default, so 
+  you will have to turn-on this option.
 
-* `DIA SDK`_ - Debug Interface Access Software Development Kit is able to read and 
-  provide more-or-less convenient access to the information stored in .pdb files. 
-  DIA SDK exposes it functionality via "COM" technology. `pygccxml`_ uses "comtypes" 
-  project to work with the API. 
+I guess, you will be surprised how much information it is possible to extract.
 
-* `BSC Toolkit`_ comes with C API. `pygccxml`_ uses "ctypes" module, from the Python 
-  standard library.
+Microsoft provides API for working with the files:
 
-Both toolkits comes with their own terminolgy. Unless you want to help me, to 
-develop this backend, you can fully ignore this fact. `pygccxml`_ bridges the 
-domains and provide clear and consistent API.
+* `DIA SDK`_ - Debug Interface Access Software Development Kit reads and gives
+  more or less convenient access to the information stored in the .pdb files. 
+  `DIA SDK`_ is an integral part of MS Visual Studio.
 
-Both files, .pdb and .bsc, contain valuable information, but some pieces are 
-presented in one file and not in other one. In near future `pygccxml`_ will be able 
-to combine the information, extracted from the files. Hint: you can send me the 
-patch :-).
+  `DIA SDK`_ exposes its functionality via "COM" technology. `pygccxml`_ uses 
+  `comtypes package`_ to work with the API. 
 
-------------------
-The backend status
-------------------
+* `Browse Source Code Toolkit`_ comes with C API. In order to read .bsc files you
+  have to `install the toolkit`_. 
+
+  `pygccxml`_ uses "ctypes" module, from the Python standard library.
+
+Both API's comes with documentation and examples. 
+
+`pygccxml`_ is going to introduce another back-end based on these tools. Each of 
+these tools doesn't tell the "whole story" about your source code, but if we 
+merge the information, extracted from the files, you can get almost the complete
+picture.
+
+
+-------------------
+The back-end status
+-------------------
 
 The short version
 -----------------
 
-I feel like this backend has "beta" state.
+The back-end has "alpha" state.
 
 The long version
 ----------------
 
-`pygccxml`_ pdb backend is able to extract almost all declarations from the .pdb 
-file. There are few exceptions and problems, that should be solved, before I will 
-consider this backend as "production" ready:
-
-* add support for bit fields - should not be a problem
-* function exception specification - this information is missing in the file
-* a declaration location within source code - from the DIA API I understand the 
-  information is there and should be available, but for some reason I can access 
-  it.
-* there is some problem with extracting the exact integral type, used in the 
-  source code - for example I have a problem to decide whether "long long int" 
-  or "long int" is used within the code. I believe, it should be possible to 
-  partially solve this problem.
-* unit test - `pygccxml`_ comes with impressive amount of unit tests. Today only 
-  small amount of them supports pdb backend. This should be fixed.
-* performance - the backend is very slow right now, but this is "by design" and 
-  I believe it is possible to improve it.
+`pygccxml`_ MSVC back-end will consist from few packages:
+
+* ``pdb`` package reads the declaration tree from the .pdb file. This package is 
+  almost complete. I still have to resolve few problems and your help is welcome:
+
+  * add support for bit fields - should not be a problem
+
+  * function exception specification - this information is missing in the file
+
+  * a declaration location within source code - from the DIA API I understand the 
+    information is there and should be available, but for some reason I can access 
+    it.
+
+  * there is some problem with extracting the exact integral type, used in the 
+    source code - for example I have a problem to decide whether "long long int" 
+    or "long int" is used within the code. I believe, it should be possible to 
+    partially solve this problem.
+
+  * unit tests - `pygccxml`_ comes with impressive amount of unit tests. Today 
+    only some of them support pdb backend.
+
+  * performance - the backend is very slow right now, but this is "by design" and 
+    I believe it is possible to improve it.
+
+* ``bsc`` package is a Python wrapper for `BSC Toolkit`_. I am almost sure, it is 
+  not possible to create "declarations tree" from the .bsc file. So this package
+  will be used to complete the information, extracted from the .pdb files.
+
+* ``msvc`` package will be the top level package that will provide a convinient 
+  access to the both sub-packages and provide "merge" functionality. As you can 
+  guess this package doesn't exist.
 
 
 .. _`DIA SDK`: http://msdn.microsoft.com/en-us/library/x93ctkx8.aspx
+.. _`Browse Source Code Toolkit` : http://www.microsoft.com/downloads/details.aspx?FamilyId=621AE185-1C2A-4D6B-8146-183D66FE709D&displaylang=en
 .. _`BSC Toolkit`: http://www.microsoft.com/downloads/details.aspx?FamilyId=621AE185-1C2A-4D6B-8146-183D66FE709D&displaylang=en
 .. _`pygccxml`: ./../pygccxml.html
 .. _`GCC-XML`: http://www.gccxml.org
+.. _`comtypes package` : http://starship.python.net/crew/theller/comtypes/
+.. _`install the toolkit` : http://www.microsoft.com/downloads/details.aspx?FamilyId=621AE185-1C2A-4D6B-8146-183D66FE709D&displaylang=en