Modernize the docs for args.

pkg/args/lib/src/usage.dart

 // Copyright (c) 2013, 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.
 
 library args.src.usage;
 
 import 'dart:math';
 
 import '../args.dart';
 
-/**
- * Takes an [ArgParser] and generates a string of usage (i.e. help) text for its
- * defined options. Internally, it works like a tabular printer. The output is
- * divided into three horizontal columns, like so:
- *
- *     -h, --help  Prints the usage information
- *     |  |        |                                 |
- *
- * It builds the usage text up one column at a time and handles padding with
- * spaces and wrapping to the next line to keep the cells correctly lined up.
- */
+/// Takes an [ArgParser] and generates a string of usage (i.e. help) text for
+/// its defined options. Internally, it works like a tabular printer. The
+/// output is divided into three horizontal columns, like so:
+///
+///     -h, --help  Prints the usage information
+///     |  |        |                                 |
+///
+/// It builds the usage text up one column at a time and handles padding with
+/// spaces and wrapping to the next line to keep the cells correctly lined up.
 class Usage {
   static const NUM_COLUMNS = 3; // Abbreviation, long name, help.
 
-  /** The parser this is generating usage for. */
+  /// The parser this is generating usage for.
   final ArgParser args;
 
-  /** The working buffer for the generated usage text. */
+  /// The working buffer for the generated usage text.
   StringBuffer buffer;
 
-  /**
-   * The column that the "cursor" is currently on. If the next call to
-   * [write()] is not for this column, it will correctly handle advancing to
-   * the next column (and possibly the next row).
-   */
+  /// The column that the "cursor" is currently on. If the next call to
+  /// [write()] is not for this column, it will correctly handle advancing to
+  /// the next column (and possibly the next row).
   int currentColumn = 0;
 
-  /** The width in characters of each column. */
+  /// The width in characters of each column.
   List<int> columnWidths;
 
-  /**
-   * The number of sequential lines of text that have been written to the last
-   * column (which shows help info). We track this so that help text that spans
-   * multiple lines can be padded with a blank line after it for separation.
-   * Meanwhile, sequential options with single-line help will be compacted next
-   * to each other.
-   */
+  /// The number of sequential lines of text that have been written to the last
+  /// column (which shows help info). We track this so that help text that spans
+  /// multiple lines can be padded with a blank line after it for separation.
+  /// Meanwhile, sequential options with single-line help will be compacted next
+  /// to each other.
   int numHelpLines = 0;
 
-  /**
-   * How many newlines need to be rendered before the next bit of text can be
-   * written. We do this lazily so that the last bit of usage doesn't have
-   * dangling newlines. We only write newlines right *before* we write some
-   * real content.
-   */
+  /// How many newlines need to be rendered before the next bit of text can be
+  /// written. We do this lazily so that the last bit of usage doesn't have
+  /// dangling newlines. We only write newlines right *before* we write some
+  /// real content.
   int newlinesNeeded = 0;
 
   Usage(this.args);
 
-  /**
-   * Generates a string displaying usage information for the defined options.
-   * This is basically the help text shown on the command line.
-   */
+  /// Generates a string displaying usage information for the defined options.
+  /// This is basically the help text shown on the command line.
   String generate() {
     buffer = new StringBuffer();
 
     calculateColumnWidths();
 
     args.options.forEach((name, option) {
       if (option.hide) return;
 
       write(0, getAbbreviation(option));
       write(1, getLongOption(option));
@@ skipping 148 matching lines @@
       if (allowed == option.defaultValue) {
         allowedBuffer.write(' (default)');
       }
       first = false;
     }
     allowedBuffer.write(']');
     return allowedBuffer.toString();
   }
 }
 
-/** Pads [source] to [length] by adding spaces at the end. */
+/// Pads [source] to [length] by adding spaces at the end.
 String padRight(String source, int length) {
   final result = new StringBuffer();
   result.write(source);
 
   while (result.length < length) {
     result.write(' ');
   }
 
   return result.toString();
 }