From 4a35fb9b4413ec8cee774821cb52ad71694c7866 Mon Sep 17 00:00:00 2001
From: Relintai <relintai@protonmail.com>
Date: Thu, 11 Jan 2024 00:32:10 +0100
Subject: [PATCH] Docs for the new classes.

---
 modules/smtp/doc_classes/EMail.xml      | 28 +++++++++++++++++++++++++
 modules/smtp/doc_classes/SMTPClient.xml | 22 +++++++++++++++++++
 2 files changed, 50 insertions(+)

diff --git a/modules/smtp/doc_classes/EMail.xml b/modules/smtp/doc_classes/EMail.xml
index 1bca7a047..4c16ffade 100644
--- a/modules/smtp/doc_classes/EMail.xml
+++ b/modules/smtp/doc_classes/EMail.xml
@@ -1,8 +1,10 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="EMail" inherits="Reference" version="4.2">
 	<brief_description>
+		Class that is used by the [SMTPClient] to send emails.
 	</brief_description>
 	<description>
+		Class that is used by the [SMTPClient] to send emails.
 	</description>
 	<tutorials>
 	</tutorials>
@@ -12,6 +14,7 @@
 			<argument index="0" name="address" type="String" />
 			<argument index="1" name="personal" type="String" />
 			<description>
+				Add an address to the Cc section of an email.
 			</description>
 		</method>
 		<method name="add_recipient">
@@ -19,33 +22,39 @@
 			<argument index="0" name="address" type="String" />
 			<argument index="1" name="personal" type="String" />
 			<description>
+				Add an address to the recipients of an email.
 			</description>
 		</method>
 		<method name="get_cc_address" qualifiers="const">
 			<return type="String" />
 			<argument index="0" name="index" type="int" />
 			<description>
+				Returns a cc's email address.
 			</description>
 		</method>
 		<method name="get_cc_count" qualifiers="const">
 			<return type="int" />
 			<description>
+				Return how many cc is set.
 			</description>
 		</method>
 		<method name="get_cc_data_string">
 			<return type="String" />
 			<description>
+				Helper emthod. Returns cc addresses formatted for the smtp protocoll.
 			</description>
 		</method>
 		<method name="get_cc_personal" qualifiers="const">
 			<return type="String" />
 			<argument index="0" name="index" type="int" />
 			<description>
+				Returns a cc's name.
 			</description>
 		</method>
 		<method name="get_ccs">
 			<return type="Array" />
 			<description>
+				Returns all ccs.
 			</description>
 		</method>
 		<method name="get_email_data_string">
@@ -53,45 +62,53 @@
 			<argument index="0" name="email_default_sender_name" type="String" />
 			<argument index="1" name="email_default_sender_email" type="String" />
 			<description>
+				Helper emthod. Returns the email's body formatted for the smtp protocoll.
 			</description>
 		</method>
 		<method name="get_recipient_address" qualifiers="const">
 			<return type="String" />
 			<argument index="0" name="index" type="int" />
 			<description>
+				Returns a recipient's email address.
 			</description>
 		</method>
 		<method name="get_recipient_count" qualifiers="const">
 			<return type="int" />
 			<description>
+				Return how many recipient is set.
 			</description>
 		</method>
 		<method name="get_recipient_personal" qualifiers="const">
 			<return type="String" />
 			<argument index="0" name="index" type="int" />
 			<description>
+				Returns a recipient's name.
 			</description>
 		</method>
 		<method name="get_recipients">
 			<return type="Array" />
 			<description>
+				Returns all recipients.
 			</description>
 		</method>
 		<method name="get_to_data_string">
 			<return type="String" />
 			<description>
+				Helper emthod. Returns the target addresses formatted for the smtp protocoll.
 			</description>
 		</method>
 		<method name="remove_cc">
 			<return type="void" />
 			<argument index="0" name="index" type="int" />
 			<description>
+				Removes a cc.
 			</description>
 		</method>
 		<method name="remove_recipient">
 			<return type="void" />
 			<argument index="0" name="index" type="int" />
 			<description>
+				Removes a recipient.
 			</description>
 		</method>
 		<method name="set_cc_address">
@@ -99,6 +116,7 @@
 			<argument index="0" name="index" type="int" />
 			<argument index="1" name="val" type="String" />
 			<description>
+				Set a recipient's email address.
 			</description>
 		</method>
 		<method name="set_cc_personal">
@@ -106,12 +124,14 @@
 			<argument index="0" name="index" type="int" />
 			<argument index="1" name="val" type="String" />
 			<description>
+				Set a cc's name.
 			</description>
 		</method>
 		<method name="set_ccs">
 			<return type="void" />
 			<argument index="0" name="ccs" type="Array" />
 			<description>
+				Set all ccs. Should countain arrays of size 2. index 0 is address, index 1 is email.
 			</description>
 		</method>
 		<method name="set_recipient_address">
@@ -119,6 +139,7 @@
 			<argument index="0" name="index" type="int" />
 			<argument index="1" name="val" type="String" />
 			<description>
+				Set a recipient's email address.
 			</description>
 		</method>
 		<method name="set_recipient_personal">
@@ -126,12 +147,14 @@
 			<argument index="0" name="index" type="int" />
 			<argument index="1" name="val" type="String" />
 			<description>
+				Set a recipient's name.
 			</description>
 		</method>
 		<method name="set_recipients">
 			<return type="void" />
 			<argument index="0" name="recipients" type="Array" />
 			<description>
+				Set all recipients. Should countain arrays of size 2. index 0 is address, index 1 is email.
 			</description>
 		</method>
 		<method name="set_sender">
@@ -139,17 +162,22 @@
 			<argument index="0" name="address" type="String" />
 			<argument index="1" name="personal" type="String" />
 			<description>
+				Shorthand for setting [member sender_address], and [member sender_personal].
 			</description>
 		</method>
 	</methods>
 	<members>
 		<member name="body" type="String" setter="set_body" getter="get_body" default="&quot;&quot;">
+			The email's body.
 		</member>
 		<member name="sender_address" type="String" setter="set_sender_address" getter="get_sender_address" default="&quot;&quot;">
+			The email's sender address. If you leave it empty the server default is used.
 		</member>
 		<member name="sender_personal" type="String" setter="set_sender_personal" getter="get_sender_personal" default="&quot;&quot;">
+			The email's sender name. If you leave it empty the server default is used.
 		</member>
 		<member name="subject" type="String" setter="set_subject" getter="get_subject" default="&quot;&quot;">
+			The email's subject.
 		</member>
 	</members>
 	<constants>
diff --git a/modules/smtp/doc_classes/SMTPClient.xml b/modules/smtp/doc_classes/SMTPClient.xml
index 6e06d8b11..aaf9d0a4d 100644
--- a/modules/smtp/doc_classes/SMTPClient.xml
+++ b/modules/smtp/doc_classes/SMTPClient.xml
@@ -1,8 +1,10 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="SMTPClient" inherits="Node" version="4.2">
 	<brief_description>
+		An SMTP Client Node.
 	</brief_description>
 	<description>
+		A Node that can be used to send emails using the SMTP protocol.
 	</description>
 	<tutorials>
 	</tutorials>
@@ -11,59 +13,79 @@
 			<return type="void" />
 			<argument index="0" name="email" type="EMail" />
 			<description>
+				Send an email.
 			</description>
 		</method>
 	</methods>
 	<members>
 		<member name="client_id" type="String" setter="set_client_id" getter="get_client_id" default="&quot;smtp.pandemoniumengine.org&quot;">
+			Client id that will be sent to the server. Not an account, it's an arbitrary value. Should not be empty.
 		</member>
 		<member name="email_default_sender_email" type="String" setter="set_email_default_sender_email" getter="get_email_default_sender_email" default="&quot;&quot;">
+			This is the address from where the email will come if you don't override it using [class EMail].
 		</member>
 		<member name="email_default_sender_name" type="String" setter="set_email_default_sender_name" getter="get_email_default_sender_name" default="&quot;&quot;">
+			This is the dislpayed name of the address from where the email will come if you don't override it using [class EMail].
 		</member>
 		<member name="host" type="String" setter="set_host" getter="get_host" default="&quot;&quot;">
+			The smtp server's host.
 		</member>
 		<member name="port" type="int" setter="set_port" getter="get_port" default="465">
+			The smtp server's port.
 		</member>
 		<member name="server_auth_method" type="int" setter="set_server_auth_method" getter="get_server_auth_method" enum="SMTPClient.ServerAuthMethod" default="1">
+			What authentication method the server uses.
 		</member>
 		<member name="server_auth_password" type="String" setter="set_server_auth_password" getter="get_server_auth_password" default="&quot;&quot;">
+			The server's account's password.
 		</member>
 		<member name="server_auth_username" type="String" setter="set_server_auth_username" getter="get_server_auth_username" default="&quot;&quot;">
+			The server's account's username.
 		</member>
 		<member name="thread_sleep_usec" type="int" setter="set_thread_sleep_usec" getter="get_thread_sleep_usec" default="10000">
+			When using threading the worker thread will wait this much time between 2 polls. 1 msec = 1000 usec.
 		</member>
 		<member name="tls_method" type="int" setter="set_tls_method" getter="get_tls_method" enum="SMTPClient.TLSMethod" default="2">
+			How to set up encryption with the server.
 		</member>
 		<member name="use_threads" type="bool" setter="set_use_threads" getter="get_use_threads" default="true">
+			Whether to use threading or not.
 		</member>
 	</members>
 	<signals>
 		<signal name="email_sent">
 			<description>
+				Emitted when an email is successfully sent.
 			</description>
 		</signal>
 		<signal name="error">
 			<argument index="0" name="error" type="Dictionary" />
 			<description>
+				Emitted when sending an email encountered an error.
 			</description>
 		</signal>
 		<signal name="result">
 			<argument index="0" name="content" type="Dictionary" />
 			<description>
+				Emitted when a email either successully sent, or encountered an error.
 			</description>
 		</signal>
 	</signals>
 	<constants>
 		<constant name="TLS_METHOD_NONE" value="0" enum="TLSMethod">
+			No encryption. Username / Password will be sent without encryption. Not recommended if you don't know what you are doing. Usual port: 587.
 		</constant>
 		<constant name="TLS_METHOD_STARTTLS" value="1" enum="TLSMethod">
+			Connect, then use the STARTTLS command, and upgarde to using SSL. Usual port: 587.
 		</constant>
 		<constant name="TLS_METHOD_SMTPS" value="2" enum="TLSMethod">
+			Connect, and immediately just set up SSL. The best option. Use this whenever you can. Usual port: 465.
 		</constant>
 		<constant name="SERVER_AUTH_PLAIN" value="0" enum="ServerAuthMethod">
+			Server does not need authentication.
 		</constant>
 		<constant name="SERVER_AUTH_LOGIN" value="1" enum="ServerAuthMethod">
+			Server needs account and password.
 		</constant>
 	</constants>
 </class>