From 3b89779736867f24d77faecd15d41bc4fdb2c927 Mon Sep 17 00:00:00 2001 From: ekatek Date: Thu, 11 Dec 2014 22:32:43 -0800 Subject: [PATCH 1/2] more, cleaner comments in Console.js This explains how to use the Console printing functions. It also moves some of the documentation around to more public functions where it will be easier for users to find. (ex: moves Console.options documentation to Console.options, rather than the internal Console.wrapText) --- tools/console.js | 110 +++++++++++++++++++++++++++++++++-------------- 1 file changed, 77 insertions(+), 33 deletions(-) diff --git a/tools/console.js b/tools/console.js index c16e09ee7e..0404ac4bf7 100644 --- a/tools/console.js +++ b/tools/console.js @@ -1,19 +1,60 @@ +/// This class provides a set of utility functions for printing to the terminal +/// in the Meteor tool. /// -/// A set of utility functions for formatting output sent to the screen. +/// When you intend for your messages to be read by humans, you should use the +/// following functions to print to the terminal. They will automatically line +/// wrap output to either the width of the terminal, or 80 characters. They +/// will also end in a new line. /// -/// Console offers several pieces of functionality: -/// - debug / info / warn messages: Output to the screen, optionally with -/// colors (when pretty == true). Wrap the output to the width of the user's -/// terminal, making sure to not split the same word over multiple -/// lines. (Also provides 'rawInfo', 'rawDebug' (etc) for when you DON'T want -/// to pre-process the output.) -/// - Progress bar support -/// Display a progress bar on the screen, but hide it around log messages. +//// - Console.info : Print to stdout. +/// - Console.error: Print to stderr. +/// - Console.warn: Prints to stderr, if warnings are enabled. +/// - Console.debug: Prints to stdout, if debug is enabled. /// -/// In future, we might do things like move all support for verbose mode in -/// here, and also integrate the buildmessage functionality into here +/// Sometimes, there is a phrase that shouldn't be split up over multiple +/// lines (for example, 'meteor update'). When applicable, please use the +/// following functions (Some of them add aditional formatting, especially when +/// pretty-print is turned on): /// - +/// - Console.command: things to enter on the command-line, such as +/// 'meteor update' or 'cd foobar'. +/// - Console.url: URLs, such as 'www.meteor.com' +/// - Console.path: filepaths outside of Console.command. +/// - Console.noWrap: anything else that you don't want line-wrapped. +/// +/// Here is a contrived example: +/// Console.info( +/// "For more information, please run", Console.command("meteor show"), +/// "or check out the new releases at", Console.url("www.meteor.com"), +/// "or look at", Console.path(filepath), ". You are currently running", +/// "Console.noWrap("Meteor version 1.5") + "."); +/// +/// The Console.info/Console.error/Console.warn/Console.debug functions also +/// take in Console.options, as a last (optional) argument. These allow you to +/// set an indent or use a bulletpoint. You can check out their API below. If +/// possible, you might also want to use one of the existing wrapper functions, +/// such as Console.labelWarning or Console.arrowInfo. +/// +/// Output intended for machines (or pre-formatted in specific ways) should NOT +/// be line-wrapped. Do not wrap these things: JSON output, error stack traces, +/// logs from other programs, etc. For those, you should use the 'raw' +/// version of the API: +/// +/// - Console.rawInfo: Like Console.info, but without formatting. +/// - Console.rawError: Like Console.error, but without formatting. +/// - Console.rawWarn: Like Console.warn, but without formatting. +/// - Console.rawDebug: Like Console.debug, but without formatting. +/// +/// DO NOT use Console.command/Console.url/Console.path with the raw functions! +/// (They will change your output in ways that you probably do not want). These +/// don't auto-linewrap, end in a newline, or take in Console.options. +/// +/// Here is are some examples: +/// Console.rawInfo(JSON.stringify(myData, null, 2)); +/// Console.rawError(err.stack + "\n"); +/// +/// In addition to printing functions, the Console class provides progress bar +/// spport, that is mostly handled through buildmessage.js. var _ = require('underscore'); var Fiber = require('fibers'); var Future = require('fibers/future'); @@ -610,10 +651,29 @@ _.extend(Console.prototype, { } }, - // Initializes and returns a new ConsoleOptions object. This allows us to call - // 'instance of' on the ConsoleOptions in parseVariadicInput, by ensuring that - // the object created with Console.options is, in fact, a new object. + // Initializes and returns a new ConsoleOptions object. Takes in the following + // Console options to pass to _wrapText eventually. + // + // - bulletPoint: start the first line with a given string, then offset the + // subsequent lines by the length of that string. For example, if the + // bulletpoint is " => ", we would get: + // " => some long message starts here + // and then continues here." + // - indent: offset the entire string by a specific number of + // characters. For example: + // " This entire message is indented + // by two characters." + // + // Passing in both options will offset the bulletPoint by the indentation, + // like so: + // " this message is indented by two." + // " => this mesage indented by two and + // and also starts with an arrow." + // options: function (o) { + // (This design pattern allows us to call 'instance of' on the + // ConsoleOptions in parseVariadicInput, by ensuring that the object created + // with Console.options is, in fact, a new object. return new ConsoleOptions(o); }, @@ -1022,25 +1082,9 @@ _.extend(Console.prototype, { // // text: the text to wrap // options: - - // - bulletPoint: start the first line with a given string, then offset the - // subsequent lines by the length of that string. For example, if the - // bulletpoint is " => ", we would get: - // " => some long message starts here - // and then continues here." - // - indent: offset the entire string by a specific number of - // characters. For example: - // " This entire message is indented - // by two characters." + // - bulletPoint: (see: Console.options) + // - indent: (see: Console.options) // - // Passing in both options will offset the bulletPoint by the indentation, - // like so: - // " this message is indented by two." - // " => this mesage indented by two and - // and also starts with an arrow." - // - // When printing commands in-line, it is best to wrap commands in with Console.command - // to make sure that they don't get line-wrapped. See Console.command for more details. _wrapText: function (text, options) { var self = this; options = options || {}; From e4a984fb6fb7d24fb9aad597b64abe46d66d9370 Mon Sep 17 00:00:00 2001 From: ekatek Date: Fri, 12 Dec 2014 11:13:45 -0800 Subject: [PATCH 2/2] fix mistype --- tools/console.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tools/console.js b/tools/console.js index 0404ac4bf7..112ba71e40 100644 --- a/tools/console.js +++ b/tools/console.js @@ -54,7 +54,7 @@ /// Console.rawError(err.stack + "\n"); /// /// In addition to printing functions, the Console class provides progress bar -/// spport, that is mostly handled through buildmessage.js. +/// support, that is mostly handled through buildmessage.js. var _ = require('underscore'); var Fiber = require('fibers'); var Future = require('fibers/future');