plugin.md updates (#1451)

* plugin.md updates

Talk about return code, logging and other bits.

Also checked the code for fmt.Printf logging, there is none.

Fixes #1449 #1450

* review

* more typos

1 files changed, 33 insertions, 0 deletions

diff --git a/plugin.md b/plugin.md
index 28168f241..f5f950884 100644
--- a/plugin.md
+++ b/plugin.md
@@ -2,11 +2,44 @@
 
 ## Writing Plugins
 
+The main method that gets called is `ServeDNS`. It has three parameters:
+
+* a `context.Context`;
+* `dns.ResponseWriter` that is, basically, the client's connection;
+* `*dns.Msg` the request from the client.
+
+`ServeDNS` returns two values, a response code and an error. If the error is not nil CoreDNS
+will return a generic SERVFAIL to the client. The response code tells CoreDNS if a reply has been
+written by the plugin chain or not. In the latter case CoreDNS will take care of that.
+
+CoreDNS treats:
+
+* SERVFAIL (dns.RcodeServerFailure)
+* REFUSED (dns.RcodeRefused)
+* FORMERR (dns.RcodeFormatError)
+* NOTIMP (dns.RcodeNotImplemented)
+
+as special and will then assume *nothing* has been written to the client. In all other cases it
+assumes something has been written to the client (by the plugin).
+
+The [*example*](https://github.com/coredns/example) plugin shows a bare-bones implementation that
+can be used as a starting point for your plugin.
+
+## Hooking It Up
+
 See a couple of blog posts on how to write and add plugin to CoreDNS:
 
 * <https://blog.coredns.io/2017/03/01/how-to-add-plugins-to-coredns/>
 * <https://blog.coredns.io/2016/12/19/writing-plugin-for-coredns/>, slightly older, but useful.
 
+## Logging
+
+If your plugin needs to output a log line you should use the `log` package. CoreDNS does not
+implement log levels. The standard way of outputing is: `log.Printf("[LEVEL] ...")`, and LEVEL
+can be: `INFO`, `WARNING` or `ERROR`.
+In general, logging should be left to the higher layers by returning an error. However, if there is
+a reason to consume the error but notify the user, then logging in the plugin can be acceptable.
+
 ## Metrics
 
 When exporting metrics the *Namespace* should be `plugin.Namespace` (="coredns"), and the