Add minimal documentation to the num class.

lib/core/num.dart

 // Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 // Dart core library.
 
 abstract class num implements Comparable, Hashable {
-  // Arithmetic operations.
+  /// Addition operator.

[Lasse Reichstein Nielsen, 2012/09/20 12:49:38]

Why the /// comments now? We don't do that anywhere else.
I prefer /** ... */ for one-liners, and find /// to blend in too well with code.

[Mads Ager (google), 2012/09/20 13:36:08]

No particular reason. I think the comment style is pretty mixed already. I
usually do /** */ too, so I'll switch to that.

   num operator +(num other);

[Lasse Reichstein Nielsen, 2012/09/20 12:49:38]

empty line after declarations (except the last in the block).

[Mads Ager (google), 2012/09/20 13:36:08]

Done.

+  /// Subtraction operator.
   num operator -(num other);
+  /// Multiplication operator.
   num operator *(num other);
+  /// Euclidean modulo operator.
   num operator %(num other);
+  /// Division operator.
   double operator /(num other);
-  // Truncating division.
+  /// Truncating division operator.
+  ///
+  /// The result of the truncating division [:a ~/ b:] is equivalent to
+  /// [:(a / b).truncate():].
   num operator ~/(num other);
-  // The unary '-' operator.
+  /// Unary minus operator.

[Lasse Reichstein Nielsen, 2012/09/20 12:49:38]

That's the negate operator.

[Mads Ager (google), 2012/09/20 13:36:08]

Done.

   num operator -();
+
+  /// Return the remainder from dividing this [num] by [other].
   num remainder(num other);
 
-  // Relational operations.
+  /// Relational less than operator.
   bool operator <(num other);
+  /// Relational less than or equal operator.
   bool operator <=(num other);
+  /// Relational greater than operator.
   bool operator >(num other);
+  /// Relational greater than or equal operator.
   bool operator >=(num other);
 
-  // Predicates.
+  /// isNan predicate.

[Lasse Reichstein Nielsen, 2012/09/20 12:49:38]

I'd rather be without this comment. It says nothing that the name of the
function don't, so we are no closer to having documented the function - but it
might seem so, which is worse than doing nothing.

Ditto for the following two.

[Mads Ager (google), 2012/09/20 13:36:08]

I have removed these comments. However, this poses the question: should I remove
most of the operator comments as well? They do not add anything either.

[Lasse Reichstein Nielsen, 2012/09/20 19:45:13]

They increase the information (not by a lot, but still) by giving names to the
operators. Saying "addition" is more meaningful than "plus" - the former is an
arithmetic operation, the latter is just the symbol.
So keep them.

   bool isNaN();
+  /// isNegative predicate.
   bool isNegative();
+  /// isInfinite predicate.
   bool isInfinite();
 
+  /// Returns the absolute value of this [num].
   num abs();
+  /// Returns the greatest integer value no greater than this [num].
+  num floor();
+  /// Returns the least integer value that is no smaller than this [num].
+  num ceil();
+
+  /// Returns the integer value closest to this [num].
+  ///
+  /// Rounds away from zero when there is no closest integer:
+  ///  [:(3.5).round() == 4:] and [:(-3.5).round() == -4:].
   num round();
-  num floor();
-  num ceil();
+
+  /// Returns the integer value obtained by discarding any fractional
+  /// digits from this [num].
   num truncate();
 
+  /// Truncates this [num] to an integer and returns the result as an [int].
   int toInt();
+
+  /// Return this [num] as a [double].

[Lasse Reichstein Nielsen, 2012/09/20 12:49:38]

///
/// If the number is not representable as a [double], an approximation
// is returned. For numberically large integers, the approximation may be
infinite.

[Mads Ager (google), 2012/09/20 13:36:08]

Done, thanks.

   double toDouble();
 
+  /// Converts a [num] to a string representation with [fractionDigits]
+  /// digits after the decimal point.
   String toStringAsFixed(int fractionDigits);
+
+  /// Converts a [num] to a string in decimal exponential notation with
+  /// [fractionDigits] digits after the decimal point.
   String toStringAsExponential(int fractionDigits);
+
+  /// Converts a [num] to a string representation with [precision]
+  /// significant digits.
   String toStringAsPrecision(int precision);
 
-  /**
-   * Converts a [num] to a string representation in the given [radix].
-   *
-   * The [num] in converted to an [int] using [toInt]. That [int] is
-   * then converted to a string representation with the given
-   * [radix]. In the string representation, lower-case letters are
-   * used for digits above '9'.
-   *
-   * The [radix] argument must be an integer between 2 and 36.
-   */
+  /// Converts a [num] to a string representation in the given [radix].
+  ///
+  /// The [num] in converted to an [int] using [toInt]. That [int] is
+  /// then converted to a string representation with the given
+  /// [radix]. In the string representation, lower-case letters are
+  /// used for digits above '9'.
+  ///
+  /// The [radix] argument must be an integer between 2 and 36.
   String toRadixString(int radix);
 }