From de83ed9b051c71a81ed3e35d3e2e39062f4784e4 Mon Sep 17 00:00:00 2001 From: simon Date: Fri, 19 May 2017 13:38:08 +0100 Subject: [PATCH] Added more package documentation --- .gitignore | 2 ++ SuiteCRMAddIn/BusinessLogic/Documentation.cs | 6 ++++++ SuiteCRMAddIn/Daemon/package.md | 7 ------- SuiteCRMAddIn/Dialogs/Documentation.cs | 11 +++++++++++ SuiteCRMAddIn/Exceptions/Documentation.cs | 6 ++++++ SuiteCRMAddIn/ProtoItems/Documentation.cs | 6 ++++++ SuiteCRMClient/Documentation.cs | 6 ++++++ SuiteCRMClient/Exceptions/Documentation.cs | 11 +++++++++++ SuiteCRMClient/RESTObjects/Documentation.cs | 6 ++++++ developers_introduction.md | 6 +++++- 10 files changed, 59 insertions(+), 8 deletions(-) create mode 100644 SuiteCRMAddIn/BusinessLogic/Documentation.cs delete mode 100644 SuiteCRMAddIn/Daemon/package.md create mode 100644 SuiteCRMAddIn/Dialogs/Documentation.cs create mode 100644 SuiteCRMAddIn/Exceptions/Documentation.cs create mode 100644 SuiteCRMAddIn/ProtoItems/Documentation.cs create mode 100644 SuiteCRMClient/Documentation.cs create mode 100644 SuiteCRMClient/Exceptions/Documentation.cs create mode 100644 SuiteCRMClient/RESTObjects/Documentation.cs diff --git a/.gitignore b/.gitignore index 31c247c8..61eaba38 100755 --- a/.gitignore +++ b/.gitignore @@ -56,3 +56,5 @@ licencekey\.txt Documentation/html/ Documentation/latex/ + +*.gz diff --git a/SuiteCRMAddIn/BusinessLogic/Documentation.cs b/SuiteCRMAddIn/BusinessLogic/Documentation.cs new file mode 100644 index 00000000..0cca9514 --- /dev/null +++ b/SuiteCRMAddIn/BusinessLogic/Documentation.cs @@ -0,0 +1,6 @@ +/// +/// The BusinessLogic package contains most of the algorithmic plumbing for the addin. +/// +namespace SuiteCRMAddIn.BusinessLogic +{ +} diff --git a/SuiteCRMAddIn/Daemon/package.md b/SuiteCRMAddIn/Daemon/package.md deleted file mode 100644 index 19a9ccd5..00000000 --- a/SuiteCRMAddIn/Daemon/package.md +++ /dev/null @@ -1,7 +0,0 @@ -# The Daemon package - -The Daemon package is intended to handle background tasks, unloading them from the user interface thread to improve the perceived responsiveness of the application. - -## DaemonWorker - -Is a singleton class which maintains a queue of tasks ('Actions') and executes them in turn. diff --git a/SuiteCRMAddIn/Dialogs/Documentation.cs b/SuiteCRMAddIn/Dialogs/Documentation.cs new file mode 100644 index 00000000..e63a1be4 --- /dev/null +++ b/SuiteCRMAddIn/Dialogs/Documentation.cs @@ -0,0 +1,11 @@ +/// +/// The Dialogs package will eventually contain all the dialogs which are used by the addin. +/// +/// +/// +/// Older forms and dialogs are found in SuiteCRMAddIn with names prefixed **frm**. The intention is that they should gradually be migrated. +/// +/// +namespace SuiteCRMAddIn.Dialogs +{ +} diff --git a/SuiteCRMAddIn/Exceptions/Documentation.cs b/SuiteCRMAddIn/Exceptions/Documentation.cs new file mode 100644 index 00000000..22ba3869 --- /dev/null +++ b/SuiteCRMAddIn/Exceptions/Documentation.cs @@ -0,0 +1,6 @@ +/// +/// The Exceptions package contains all custom exceptions used by the addin. +/// +namespace SuiteCRMAddIn.Exceptions +{ +} diff --git a/SuiteCRMAddIn/ProtoItems/Documentation.cs b/SuiteCRMAddIn/ProtoItems/Documentation.cs new file mode 100644 index 00000000..8f2d8e25 --- /dev/null +++ b/SuiteCRMAddIn/ProtoItems/Documentation.cs @@ -0,0 +1,6 @@ +/// +/// ProtoItems are C# implementations of CRM classes, in order to make serialising to JSON easier. +/// +namespace SuiteCRMAddIn.ProtoItems +{ +} diff --git a/SuiteCRMClient/Documentation.cs b/SuiteCRMClient/Documentation.cs new file mode 100644 index 00000000..f4b348a7 --- /dev/null +++ b/SuiteCRMClient/Documentation.cs @@ -0,0 +1,6 @@ +/// +/// SuiteCRMClient is a client library for the SuiteCRM JSON API. +/// +namespace SuiteCRMClient +{ +} diff --git a/SuiteCRMClient/Exceptions/Documentation.cs b/SuiteCRMClient/Exceptions/Documentation.cs new file mode 100644 index 00000000..3ffc873e --- /dev/null +++ b/SuiteCRMClient/Exceptions/Documentation.cs @@ -0,0 +1,11 @@ +/// +/// The Exceptions package contains all custom exceptions used by the client. +/// +/// +/// +/// 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. +/// +/// +namespace SuiteCRMClient.Exceptions +{ +} diff --git a/SuiteCRMClient/RESTObjects/Documentation.cs b/SuiteCRMClient/RESTObjects/Documentation.cs new file mode 100644 index 00000000..395b8ecc --- /dev/null +++ b/SuiteCRMClient/RESTObjects/Documentation.cs @@ -0,0 +1,6 @@ +/// +/// The RESTObjects package contains classes which may be deserialised from JSON messages sent by CRM. +/// +namespace SuiteCRMClient.RESTObjects +{ +} diff --git a/developers_introduction.md b/developers_introduction.md index 827afc37..68971a7c 100644 --- a/developers_introduction.md +++ b/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.