From 958f4e300f79242299ba96dfb72b47a6ef72c4df Mon Sep 17 00:00:00 2001
From: Niko Ehrenfeuchter <nikolaus.ehrenfeuchter@unibas.ch>
Date: Fri, 19 Jan 2018 14:10:05 +0100
Subject: [PATCH] Add missing docstrings for serializable attributes.
---
ATXCommon/Serializables/DriveToCheck.cs | 9 ++-
ATXCommon/Serializables/ServiceConfig.cs | 70 +++++++++++++++++++++++-
ATXCommon/Serializables/ServiceStatus.cs | 40 ++++++++++++++
3 files changed, 116 insertions(+), 3 deletions(-)
diff --git a/ATXCommon/Serializables/DriveToCheck.cs b/ATXCommon/Serializables/DriveToCheck.cs
index 35a0242..553f475 100644
--- a/ATXCommon/Serializables/DriveToCheck.cs
+++ b/ATXCommon/Serializables/DriveToCheck.cs
@@ -7,11 +7,16 @@ namespace ATXCommon.Serializables
/// </summary>
public class DriveToCheck
{
+ /// <summary>
+ /// A drive name (single letter followed by a colon, e.g. "D:") to be monitored for space.
+ /// </summary>
[XmlElement("DriveName")]
public string DriveName { get; set; }
- // the value is to be compared to System.IO.DriveInfo.TotalFreeSpace
- // hence we use the same type (long) to avoid unnecessary casts later:
+ /// <summary>
+ /// Limit (in MB) of free space, lower values will trigger a notification.
+ /// </summary>
+ /// Value is to be compared to DriveInfo.TotalFreeSpace, hence the same type (long).
[XmlElement("SpaceThreshold")]
public long SpaceThreshold { get; set; }
}
diff --git a/ATXCommon/Serializables/ServiceConfig.cs b/ATXCommon/Serializables/ServiceConfig.cs
index eba8b41..81f2d02 100644
--- a/ATXCommon/Serializables/ServiceConfig.cs
+++ b/ATXCommon/Serializables/ServiceConfig.cs
@@ -9,7 +9,7 @@ using NLog.Config;
namespace ATXCommon.Serializables
{
/// <summary>
- /// configuration class based on xml
+ /// AutoTx service configuration class.
/// </summary>
[Serializable]
public class ServiceConfig
@@ -79,13 +79,35 @@ namespace ATXCommon.Serializables
/// </summary>
public string TmpTransferDir { get; set; }
+ /// <summary>
+ /// The email address to be used as "From:" when sending mail notifications.
+ /// </summary>
public string EmailFrom { get; set; }
+ /// <summary>
+ /// The interval (in ms) for checking for new files and system parameters.
+ /// </summary>
public int ServiceTimer { get; set; }
+ /// <summary>
+ /// Maximum allowed CPU usage across all cores in percent. Running transfers will be paused
+ /// if this limit is exceeded.
+ /// </summary>
public int MaxCpuUsage { get; set; }
+
+ /// <summary>
+ /// Minimum amount of free RAM (in MB) required for the service to operate.
+ /// </summary>
public int MinAvailableMemory { get; set; }
+
+ /// <summary>
+ /// Minimum amount of time in minutes between two mail notifications to the admin address.
+ /// </summary>
public int AdminNotificationDelta { get; set; }
+
+ /// <summary>
+ /// Minimum amount of time in minutes between two low-storage-space notifications.
+ /// </summary>
public int StorageNotificationDelta { get; set; }
/// <summary>
@@ -94,8 +116,19 @@ namespace ATXCommon.Serializables
/// </summary>
public int GracePeriod { get; set; }
+ /// <summary>
+ /// Flag whether to send explicit mail notifications to the admin on selected events.
+ /// </summary>
public bool SendAdminNotification { get; set; }
+
+ /// <summary>
+ /// Flag whether to send a mail notification to the user upon completed transfers.
+ /// </summary>
public bool SendTransferNotification { get; set; }
+
+ /// <summary>
+ /// Switch on debug log messages.
+ /// </summary>
public bool Debug { get; set; }
[XmlArray]
@@ -111,17 +144,52 @@ namespace ATXCommon.Serializables
#region optional configuration parameters
+ /// <summary>
+ /// SMTP server used to send mails (if configured) and Fatal/Error log messages.
+ ///
+ /// No mails will be sent if this is omitted.
+ /// </summary>
public string SmtpHost { get; set; }
+
+ /// <summary>
+ /// SMTP username to authenticate when sending emails (if required).
+ /// </summary>
public string SmtpUserCredential { get; set; }
+
+ /// <summary>
+ /// SMTP password to authenticate when sending emails (if required).
+ /// </summary>
public string SmtpPasswortCredential { get; set; }
+
+ /// <summary>
+ /// SMTP port for sending emails (25 will be used if this entry is omitted).
+ /// </summary>
public int SmtpPort { get; set; }
+ /// <summary>
+ /// A string to be added as a prefix to the subject when sending emails.
+ /// </summary>
public string EmailPrefix { get; set; }
+
+ /// <summary>
+ /// The mail recipient address for admin notifications (including "Fatal" log messages).
+ /// </summary>
public string AdminEmailAdress { get; set; }
+
+ /// <summary>
+ /// The mail recipient address for debug notifications (including "Error" log messages).
+ /// </summary>
public string AdminDebugEmailAdress { get; set; }
+ /// <summary>
+ /// Minimum time in minutes between two mails about expired folders in the grace location.
+ /// </summary>
public int GraceNotificationDelta { get; set; }
+ /// <summary>
+ /// RoboCopy parameter for limiting the bandwidth (mostly for testing purposes).
+ /// </summary>
+ /// See the RoboCopy documentation for more details.
public int InterPacketGap { get; set; }
/// <summary>
diff --git a/ATXCommon/Serializables/ServiceStatus.cs b/ATXCommon/Serializables/ServiceStatus.cs
index 3283b31..8d8b116 100644
--- a/ATXCommon/Serializables/ServiceStatus.cs
+++ b/ATXCommon/Serializables/ServiceStatus.cs
@@ -5,6 +5,9 @@ using NLog;
namespace ATXCommon.Serializables
{
+ /// <summary>
+ /// AutoTx service status class.
+ /// </summary>
[Serializable]
public class ServiceStatus
{
@@ -28,12 +31,19 @@ namespace ATXCommon.Serializables
private long _currentTransferSize;
+
+ /// <summary>
+ /// Timestamp indicating when the status has been updated last ("heartbeat").
+ /// </summary>
[XmlElement("LastStatusUpdate", DataType = "dateTime")]
public DateTime LastStatusUpdate {
get { return _lastStatusUpdate; }
set { _lastStatusUpdate = value; }
}
+ /// <summary>
+ /// Timestamp indicating when the last storage notification has been sent.
+ /// </summary>
[XmlElement("LastStorageNotification", DataType = "dateTime")]
public DateTime LastStorageNotification {
get { return _lastStorageNotification; }
@@ -43,6 +53,9 @@ namespace ATXCommon.Serializables
}
}
+ /// <summary>
+ /// Timestamp indicating when the last admin notification has been sent.
+ /// </summary>
[XmlElement("LastAdminNotification", DataType = "dateTime")]
public DateTime LastAdminNotification {
get { return _lastAdminNotification; }
@@ -52,6 +65,9 @@ namespace ATXCommon.Serializables
}
}
+ /// <summary>
+ /// Timestamp indicating when the last notification on expired folders has been sent.
+ /// </summary>
[XmlElement("LastGraceNotification", DataType = "dateTime")]
public DateTime LastGraceNotification {
get { return _lastGraceNotification; }
@@ -61,6 +77,9 @@ namespace ATXCommon.Serializables
}
}
+ /// <summary>
+ /// String indicating why the service is currently suspended (empty if not suspended).
+ /// </summary>
public string LimitReason {
get { return _limitReason; }
set {
@@ -70,6 +89,9 @@ namespace ATXCommon.Serializables
}
}
+ /// <summary>
+ /// The full path to the folder currently being transferred.
+ /// </summary>
public string CurrentTransferSrc {
get { return _currentTransferSrc; }
set {
@@ -79,6 +101,11 @@ namespace ATXCommon.Serializables
}
}
+ /// <summary>
+ /// The name of the temporary folder being used for the currently running transfer,
+ /// relative to "DestinationDirectory\TmpTransferDir" (i.e. the target username). See also
+ /// <seealso cref="CurrentTargetTmpFull"/> on details for assembling the full path.
+ /// </summary>
public string CurrentTargetTmp {
get { return _currentTargetTmp; }
set {
@@ -88,6 +115,9 @@ namespace ATXCommon.Serializables
}
}
+ /// <summary>
+ /// Flag indicating whether the service is currently suspended.
+ /// </summary>
public bool ServiceSuspended {
get { return _serviceSuspended; }
set {
@@ -97,6 +127,9 @@ namespace ATXCommon.Serializables
}
}
+ /// <summary>
+ /// Flag indicating whether a transfer is currently running.
+ /// </summary>
public bool TransferInProgress {
get { return _transferInProgress; }
set {
@@ -117,6 +150,9 @@ namespace ATXCommon.Serializables
}
}
+ /// <summary>
+ /// The full size of the current transfer in bytes.
+ /// </summary>
public long CurrentTransferSize {
get { return _currentTransferSize; }
set {
@@ -202,6 +238,10 @@ namespace ATXCommon.Serializables
}
}
+ /// <summary>
+ /// Generate a human-readable sumary of the current transfer.
+ /// </summary>
+ /// <returns>A string with details on the transfer.</returns>
public string Summary() {
return
"CurrentTransferSrc: " + CurrentTransferSrc + "\n" +
--
GitLab