Update doc comment guidelines (#49)

.github/PULL_REQUEST_TEMPLATE.md

@@ -14,6 +14,6 @@
 Please include the following checklist in your PR:
 
 - [ ] The documentation has been updated if necessary.
-- [ ] The code conforms to the [Scala](https://github.com/luna/enso/blob/master/doc/scala-style-guide.md), [Java](https://github.com/luna/enso/blob/master/doc/java-style-guide.md) or [Haskell](https://github.com/luna/enso/blob/master/doc/haskell-style-guide.md) style guides as appropriate.
-- [ ] The code has been tested where possible.
+- [ ] All code conforms to the [Scala](https://github.com/luna/enso/blob/master/doc/scala-style-guide.md), [Java](https://github.com/luna/enso/blob/master/doc/java-style-guide.md) or [Haskell](https://github.com/luna/enso/blob/master/doc/haskell-style-guide.md) style guides as appropriate.
+- [ ] All code has been tested where possible.
 

doc/haskell-style-guide.md

@@ -262,11 +262,19 @@ to revisiting this decision; if you know of a tool that would let us automate
 the above stylistic rules, then please speak up.
 
 ## Commenting
-Comments are a tricky area to get right, as we have found that comments often
-expire quickly and, in absence of a way to validate them, remain incorrect for
-long periods of time. That is not to say, however, that we eschew comments
-entirely. Instead, we make keeping comments up to date an integral part of our
-programming practice, while also limiting the types of comments that we allow.
+Comments in code are a tricky area to get right as we have found that comments
+often expire quickly, and in absence of a way to validate them, remain incorrect
+for long periods of time. In order to best deal with this problem, we make the
+keeping of comments up-to-date into an integral part of our programming practice
+while also limiting the types and kinds of comments we allow.
+
+Comments across the Enso codebases fall into three main types:
+
+- **Documentation Comments:** API documentation for all language constructs that
+  can have it (functions, typeclasses, and so on).
+- **Source Notes:** Detailed explorations of design reasoning that avoid
+  cluttering the code itself.
+- **Tasks:** Things that need doing or fixing in the codebase.
 
 When we write comments, we try to follow one general guideline. A comment should
 explain _what_ and _why_, without mentioning _how_. The _how_ should be
@@ -278,8 +286,9 @@ comments should not be used as a crutch for badly-designed code.
 
 ### Documentation Comments
 One of the primary forms of comment that we allow across the Enso codebases is
-the doc comment. These are intended to be consumed by users of the API, and use
-the standard Haddock syntax. Doc comments should:
+the doc comment. Every language construct that can have an associated doc
+comment should do so. These are intended to be consumed by users of the API, and
+use the standard Haddock syntax. Doc comments should:
 
 - Provide a short one-line explanation of the object being documented.
 - Provide a longer description of the object, including examples where relevant.

doc/java-style-guide.md

@@ -49,11 +49,19 @@ below may provide more rules for use in specific cases.
 - Names should be descriptive, even if this makes them longer.
 
 ## Commenting
-Comments are a tricky area to get right, as we have found that comments often
-expire quickly and, in absence of a way to validate them, remain incorrect for
-long periods of time. That is not to say, however, that we eschew comments
-entirely. Instead, we make keeping comments up to date an integral part of our
-programming practice, while also limiting the types of comments that we allow.
+Comments in code are a tricky area to get right as we have found that comments
+often expire quickly, and in absence of a way to validate them, remain incorrect
+for long periods of time. In order to best deal with this problem, we make the
+keeping of comments up-to-date into an integral part of our programming practice
+while also limiting the types and kinds of comments we allow.
+
+Comments across the Enso codebases fall into three main types:
+
+- **Documentation Comments:** API documentation for all language constructs that
+  can have it (classes, methods, and so on).
+- **Source Notes:** Detailed explorations of design reasoning that avoid
+  cluttering the code itself.
+- **Tasks:** Things that need doing or fixing in the codebase.
 
 When we write comments, we try to follow one general guideline. A comment should
 explain _what_ and _why_, without mentioning _how_. The _how_ should be
@@ -65,8 +73,10 @@ comments should not be used as a crutch for badly-designed code.
 
 ### Documentation Comments
 One of the primary forms of comment that we allow across the Enso codebases is
-the doc comment. These are intended to be consumed by users of the API, and use
-the standard Javadoc syntax. Doc comments should:
+the doc comment. Every language construct that can have an associated doc
+comment should do so. These are intended to be consumed by users of the API,
+whether internal or external, and use the standard Javadoc syntax. Doc comments
+should:
 
 - Provide a short one-line explanation of the object being documented.
 - Provide a longer description of the object, including examples where relevant.

doc/scala-style-guide.md

@@ -37,8 +37,8 @@ should be used for all new Scala projects.
 All files must be formatted using `scalafmt` before commit, and this should be
 set up as either a precommit hook, or using the integration in IntelliJ. If you
 use the IntelliJ integration, please note that you need only have the official
-[Scala Plugin](https://www.jetbrains.com/help/idea/discover-intellij-idea-for-scala.html) 
-installed, and be using IntelliJ 2019.1 or later. You should _not_ use the 
+[Scala Plugin](https://www.jetbrains.com/help/idea/discover-intellij-idea-for-scala.html)
+installed, and be using IntelliJ 2019.1 or later. You should _not_ use the
 independent Scalafmt plugin.
 
 ### Naming
@@ -62,11 +62,19 @@ If you are using IntelliJ, please ensure that you select to use the SBT shell
 for both imports and builds.
 
 ## Commenting
-Comments are a tricky area to get right, as we have found that comments often
-expire quickly and, in absence of a way to validate them, remain incorrect for
-long periods of time. That is not to say, however, that we eschew comments
-entirely. Instead, we make keeping comments up to date an integral part of our
-programming practice, while also limiting the types of comments that we allow.
+Comments in code are a tricky area to get right as we have found that comments
+often expire quickly, and in absence of a way to validate them, remain incorrect
+for long periods of time. In order to best deal with this problem, we make the
+keeping of comments up-to-date into an integral part of our programming practice
+while also limiting the types and kinds of comments we allow.
+
+Comments across the Enso codebases fall into three main types:
+
+- **Documentation Comments:** API documentation for all language constructs that
+  can have it (classes, objects, functions, and so on).
+- **Source Notes:** Detailed explorations of design reasoning that avoid
+  cluttering the code itself.
+- **Tasks:** Things that need doing or fixing in the codebase.
 
 When we write comments, we try to follow one general guideline. A comment should
 explain _what_ and _why_, without mentioning _how_. The _how_ should be
@@ -78,9 +86,10 @@ comments should not be used as a crutch for badly-designed code.
 
 ### Documentation Comments
 One of the primary forms of comment that we allow across the Enso codebases is
-the doc comment. These are intended to be consumed by users of the API, and use
-the standard [scaladoc](https://docs.scala-lang.org/style/scaladoc.html) syntax.
-Doc comments should:
+the doc comment. Every language construct that can have an associated doc
+comment should do so. These are intended to be consumed by users of the API, and
+use the standard [scaladoc](https://docs.scala-lang.org/style/scaladoc.html)
+syntax. Doc comments should:
 
 - Provide a short one-line explanation of the object being documented.
 - Provide a longer description of the object, including examples where relevant.