From 49b2836d98e32eee253e853a9ab572df11c4755e Mon Sep 17 00:00:00 2001 From: simon Date: Fri, 19 May 2017 12:47:01 +0100 Subject: [PATCH] Documentation with working images --- Doxyfile | 10 +++++----- SuiteCRMAddIn/Daemon/DaemonAction.cs | 12 +++++++----- SuiteCRMAddIn/Daemon/documentation.cs | 18 ++++++++++++++++++ SuiteCRMAddIn/Daemon/package.md | 7 +++++++ developers_introduction.md | 19 +++++++++++++++++++ 5 files changed, 56 insertions(+), 10 deletions(-) create mode 100644 SuiteCRMAddIn/Daemon/documentation.cs create mode 100644 SuiteCRMAddIn/Daemon/package.md create mode 100644 developers_introduction.md diff --git a/Doxyfile b/Doxyfile index 4e6a6c28..2ffc8f0d 100644 --- a/Doxyfile +++ b/Doxyfile @@ -58,7 +58,7 @@ PROJECT_LOGO = SuiteCRMAddIn/Images/SuiteCRM.jpg # entered, it will be relative to the location where doxygen was started. If # left blank the current directory will be used. -OUTPUT_DIRECTORY = "C:\Users\simon\Documents\Visual Studio 2015\Projects\SuiteCRM-Outlook-Plugin\Documentation" +OUTPUT_DIRECTORY = Documentation # If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub- # directories (in 2 levels) under the output directory of each output format and @@ -790,7 +790,7 @@ WARN_LOGFILE = # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING # Note: If this tag is empty the current directory is searched. -INPUT = "C:\Users\simon\Documents\Visual Studio 2015\Projects\SuiteCRM-Outlook-Plugin" +INPUT = # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses @@ -2374,7 +2374,7 @@ DIRECTORY_GRAPH = YES # The default value is: png. # This tag requires that the tag HAVE_DOT is set to YES. -DOT_IMAGE_FORMAT = svg +DOT_IMAGE_FORMAT = png # If DOT_IMAGE_FORMAT is set to svg, then this option can be set to YES to # enable generation of interactive SVG images that allow zooming and panning. @@ -2386,13 +2386,13 @@ DOT_IMAGE_FORMAT = svg # The default value is: NO. # This tag requires that the tag HAVE_DOT is set to YES. -INTERACTIVE_SVG = YES +INTERACTIVE_SVG = NO # The DOT_PATH tag can be used to specify the path where the dot tool can be # found. If left blank, it is assumed the dot tool can be found in the path. # This tag requires that the tag HAVE_DOT is set to YES. -DOT_PATH = c:/Program Files (x86)/Graphviz2.38/bin/dot +DOT_PATH = # The DOTFILE_DIRS tag can be used to specify one or more directories that # contain dot files that are included in the documentation (see the \dotfile diff --git a/SuiteCRMAddIn/Daemon/DaemonAction.cs b/SuiteCRMAddIn/Daemon/DaemonAction.cs index d432d442..dfbf71bc 100644 --- a/SuiteCRMAddIn/Daemon/DaemonAction.cs +++ b/SuiteCRMAddIn/Daemon/DaemonAction.cs @@ -22,11 +22,13 @@ */ namespace SuiteCRMAddIn.Daemon { - /// Not currently used. You can't make a list of Outlook items detached from their - /// Outlook collection because they're not real objects, and if the current selection changes - /// before the process runs the process acts on the wrong things. I like the idea of - /// asynchronous processing to speed up perceived user interface response, but this isn't - /// working yet. + /// An action to be queued and performed by the DaemonWorker. + /// + /// DaemonActions are intended to be run essentially once, but may be allowed a number of attempts + /// (intended to be limited) in case, for example due to network problems, the first attempt(s) fail. + /// However, DaemonActions are not intended for things which are to be run repeatedly. For that, + /// specialise [RepeatingProcess](class_suite_c_r_m_add_in_1_1_business_logic_1_1_repeating_process.html). + /// public interface DaemonAction { /// diff --git a/SuiteCRMAddIn/Daemon/documentation.cs b/SuiteCRMAddIn/Daemon/documentation.cs new file mode 100644 index 00000000..1cf57501 --- /dev/null +++ b/SuiteCRMAddIn/Daemon/documentation.cs @@ -0,0 +1,18 @@ +/// +/// The Daemon package is intended to handle background tasks, unloading them from the user +/// interface thread to improve the perceived responsiveness of the application. +/// +/// +/// +/// A singleton instance of DaemonWorker runs as a RepeatingProcess in a thread; it maintains a +/// queue of DaemonActions, which it executes in turn. +/// +/// +/// Instances of classes implementing DaemonAction are intended to be run essentially once, but may be allowed a number of attempts +/// (intended to be limited) in case, for example due to network problems, the first attempt(s) fail. +/// However, DaemonAction is not intended for things which are to be run repeatedly. For that, +/// specialise [RepeatingProcess](class_suite_c_r_m_add_in_1_1_business_logic_1_1_repeating_process.html). +/// +namespace SuiteCRMAddIn.Daemon +{ +} diff --git a/SuiteCRMAddIn/Daemon/package.md b/SuiteCRMAddIn/Daemon/package.md new file mode 100644 index 00000000..19a9ccd5 --- /dev/null +++ b/SuiteCRMAddIn/Daemon/package.md @@ -0,0 +1,7 @@ +# 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/developers_introduction.md b/developers_introduction.md new file mode 100644 index 00000000..827afc37 --- /dev/null +++ b/developers_introduction.md @@ -0,0 +1,19 @@ +# Introduction for Developers + +## History + +The SuiteCRM Outlook Add-in has a history, and it's fairly important to understand that when working on it. The earliest commits in the current repository are by [Will Rennie](https://github.com/willrennie), but he wasn't responsible for the original design, instead inheriting a pre-existing codebase. Will improved the codebase to some extent between May 2014 and January 2017. [Andrew Forrest](https://github.com/bunsen32) then took over briefly. Andrew is a very experienced and expert software engineer who actually likes C#, and did a considerable amount of refactoring which improved the code greatly. In March 2017 [Simon Brooke](https://github.com/simon-brooke) took over. Simon is an aging and grumpy Lisp hacker who loathes everything produced by Microsoft generally, and C# particularly, with a passion. Simon has hacked around the codebase and made stuff work. + +But this tangled history leads to a variety of styles, and this can be hard to follow. + +Parts of the original codebase were startlingly bad, with tangled nests of GOTO statements; Simon has a suspicion that the original code was produced using a nasty point-and-drool paint-an-app tool by some *Microsoft Certified Software Professional*, probably originally as Visual BASIC, and then automatically converted to C# with some equally nasty tool. He can find no other explanation for its deep horridness. There was no design documentation, or if there was it has long been lost. There was no inline documentation. Consequently everyone working on it since has been working blind; we've all tried to improve it in our different ways, and on the whole the general quality is now much better. + +Parts of the ugliness remain, however. + +The original code makes heavy use of Hungarian notation, and nothing conformed to normal C# naming conventions. The conventional Microsoft Settings class was not used, but instead a custom 'clsSettings'; and classes were originally primarily in the SuiteCRMAddIn namespace with no real structure. + +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. + +