Added more package documentation

.gitignore

@@ -56,3 +56,5 @@ licencekey\.txt
 Documentation/html/
 
 Documentation/latex/
+
+*.gz

SuiteCRMAddIn/BusinessLogic/Documentation.cs

@@ -0,0 +1,6 @@
+/// <summary>
+/// The BusinessLogic package contains most of the algorithmic plumbing for the addin.
+/// </summary>
+namespace SuiteCRMAddIn.BusinessLogic
+{
+}

SuiteCRMAddIn/Dialogs/Documentation.cs

@@ -0,0 +1,11 @@
+/// <summary>
+/// The Dialogs package will eventually contain all the dialogs which are used by the addin.
+/// </summary>
+/// <remarks>
+/// <para>
+/// Older forms and dialogs are found in SuiteCRMAddIn with names prefixed **frm**. The intention is that they should gradually be migrated.
+/// </para>
+/// </remarks>
+namespace SuiteCRMAddIn.Dialogs
+{
+}

SuiteCRMAddIn/Exceptions/Documentation.cs

@@ -0,0 +1,6 @@
+/// <summary>
+/// The Exceptions package contains all custom exceptions used by the addin.
+/// </summary>
+namespace SuiteCRMAddIn.Exceptions
+{
+}

SuiteCRMAddIn/ProtoItems/Documentation.cs

@@ -0,0 +1,6 @@
+/// <summary>
+/// ProtoItems are C# implementations of CRM classes, in order to make serialising to JSON easier.
+/// </summary>
+namespace SuiteCRMAddIn.ProtoItems
+{
+}

SuiteCRMClient/Documentation.cs

@@ -0,0 +1,6 @@
+/// <summary>
+/// SuiteCRMClient is a client library for the SuiteCRM JSON API.
+/// </summary>
+namespace SuiteCRMClient
+{
+}

SuiteCRMClient/Exceptions/Documentation.cs

@@ -0,0 +1,11 @@
+/// <summary>
+/// The Exceptions package contains all custom exceptions used by the client.
+/// </summary>
+/// <remarks>
+/// <para>
+/// In the older code there is a widespread practice of throwing raw instances of Exception. This is bad practice, and those raw exceptions should gradually be replaced by specialised exceptions. At the time of writing there are still 7 raw exceptions thrown.
+/// </para>
+/// </remarks>
+namespace SuiteCRMClient.Exceptions
+{
+}

SuiteCRMClient/RESTObjects/Documentation.cs

@@ -0,0 +1,6 @@
+/// <summary>
+/// The RESTObjects package contains classes which may be deserialised from JSON messages sent by CRM.
+/// </summary>
+namespace SuiteCRMClient.RESTObjects
+{
+}

developers_introduction.md

@@ -14,6 +14,10 @@ The original code makes heavy use of Hungarian notation, and nothing conformed t
 
 This is being improved, gradually. Newly created forms and dialogs, for example, are now in the namespace SuiteCRMAddin.Dialogs, and have class names ending in **Dialog**, whereas older forms and dialogs are found in SuiteCRMAddIn with names prefixed **frm**. The intention is that they should gradually be migrated.
 
-Broadly, all inline documentation has been written by Simon; at the point that he took over there was very little inline documentation at all. He is to be blamed, therefore, for all the bits that are wrong or out of date.
+## Documentation
+
+Documentation is partial and incomplete; and, since we don't know the original designers intention and have had to infer it from the code, some may be mistaken or just plain wrong. We are gradually trying to improve this situation.
 
+Broadly, all inline documentation has been written by Simon; at the point that he took over there was very little inline documentation at all. He is to be blamed, therefore, for all the bits that are wrong or out of date.
 
+HTML documentation is generated from the inline documentation using [doxygen](https://www.stack.nl/~dimitri/doxygen/). **The HTML documentation should never be directly edited**. Instead please edit inline documentation in the code, and regenerate with doxygen. A convention has been adopted of adding a file *Documentation.cs* to each package, to contain package level documentation. By convention this file should contain no class or other code.