Added basic SMTP documentation and examples

[etcimon]

The documentation was a little underwhelming in the SMTP module, and I thought the sendmail example in the examples/ directory was quite unhelpful as a quick reference. So, this change serves its purpose of explaining how to send a basic message through sendMail, so that anyone can get his solution up within a couple minutes.

[s-ludwig]

Thanks, you are right, documentation is a bit thin there. Two corrections/improvements for the doc comment:

• The first paragraph is also the short description of the symbol, so the most simple correction would be to put the first sentence on its own paragraph.

• The example should be in a documented unit test, so that it is automatically checked to compile:

  ///
  unittest {
      void test()
      {
          auto settings = new SMTPClientSettings(...);
          // ...
      }
  }
  

Also, do you think that sending the mail from within a HTTP request handler adds any value to the documentation? It seems to be a bit out of place to me when looking at it from a "neutral" point of view.

[etcimon]

Also, do you think that sending the mail from within a HTTP request handler adds any value to the documentation? It seems to be a bit out of place to me when looking at it from a "neutral" point of view.

I probably over-did it, I would surely be better to remove the variables altogether.

The first paragraph is also the short description of the symbol, so the most simple correction would be to put the first sentence on its own paragraph.

The example should be in a documented unit test, so that it is automatically checked to compile:

So the /// registers this unit test as an example?

[s-ludwig]

Exactly, you could also write some text that would appear before the example. This is a relatively recent feature of DMD/Ddoc (not sure if 2.064 or 2.065) that is now also supported for DDOX.

[etcimon]

This should be passing, the logs seem to complain about the Redis test

[s-ludwig]

The failure looks strange, but your changes indeed look good. I'll merge and correct the documentation comment.

[etcimon]

Thanks !

The first paragraph is also the short description of the symbol, so the most simple correction would be to put the first sentence on its own paragraph.

I must have not understood this, which symbol does it describe?

[s-ludwig]

The first paragraph of a Ddoc comment (where a paragraph is a set of one or more lines delimited by one or more empty lines) is defined to be the "short summary" for the documented symbol as per the Ddoc specification. It is used by DDOX to populate the overview tables. This first paragraph should be relatively short, around maybe 60 to 120 characters.