some cleanup to the stdout messages we print

[devoncarew]

This normalizes the blank lines and title case of the stdout we print when generating docs. After this change:

Generating documentation for 'analysis_server_lib' into /Users/devoncarew/projects/devoncarew/analysis_server_lib/doc/api/

parsing lib/analysis_server_lib.dart...
parsed 14 files in 5.6 seconds

generating docs for library analysis_server_lib from analysis_server_lib.dart...
generating docs for library dart:async from async.dart...
 warning: unresolved doc reference [Stream.groupByMapped], from dart-async.StreamGroup (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/async/stream.dart:1916:7)
 warning: unresolved doc reference [cleanup], from dart-async.Future.wait (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/async/future.dart:316:26)
 warning: unresolved doc reference [GroupBy], from dart-async.StreamGroup.values (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/async/stream.dart:1921:19)
generating docs for library dart:collection from collection.dart...
 warning: unresolved doc reference [contains], from dart-collection.MapBase (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/collection/maps.dart:23:16)
 warning: unresolved doc reference [contains], from dart-collection.MapMixin (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/collection/maps.dart:41:16)
 warning: unresolved doc reference [contains], from dart-collection.UnmodifiableMapBase (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/collection/maps.dart:103:16)
 warning: unresolved doc reference [test], from dart-collection.DoubleLinkedQueue.any (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/core/iterable.dart:333:8)
 warning: unresolved doc reference [test], from dart-collection.DoubleLinkedQueue.every (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/core/iterable.dart:294:8)
 warning: unresolved doc reference [test], from dart-collection.HashSet.any (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/core/iterable.dart:333:8)
 warning: unresolved doc reference [test], from dart-collection.HashSet.every (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/core/iterable.dart:294:8)
 warning: unresolved doc reference [test], from dart-collection.LinkedHashSet.any (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/core/iterable.dart:333:8)
 warning: unresolved doc reference [test], from dart-collection.LinkedHashSet.every (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/core/iterable.dart:294:8)
 warning: unresolved doc reference [a], from dart-collection.List.lastIndexOf (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/core/list.dart:278:7)
 warning: no canonical library found for dart-_internal.EfficientLengthIterable, not linking (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/internal/iterable.dart:11:16)
 warning: no canonical library found for dart-_internal.ListIterable, not linking (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/internal/iterable.dart:28:16)
 warning: unresolved doc reference [f], from dart-collection.Iterable.forEach (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/core/iterable.dart:225:8)
 warning: unresolved doc reference [test], from dart-collection.Queue.any (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/core/iterable.dart:333:8)
 warning: unresolved doc reference [test], from dart-collection.Queue.every (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/core/iterable.dart:294:8)
 warning: unresolved doc reference [value], from dart-collection.Set.add (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/core/set.dart:111:8)
 warning: unresolved doc reference [element], from dart-collection.Iterable.contains (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/core/iterable.dart:214:8)
 warning: unresolved doc reference [value], from dart-collection.Set.remove (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/core/set.dart:126:8)
 warning: no canonical library found for dart-_internal.UnmodifiableListBase, not linking (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/internal/list.dart:200:16)
generating docs for library dart:convert from convert.dart...
generating docs for library dart:core from core.dart...
generating docs for library dart:developer from developer.dart...
generating docs for library dart:io from io.dart...
 warning: unresolved doc reference [host], from dart-io.HttpClient.openUrl (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/io/http.dart:1377:29)
 warning: unresolved doc reference [RECEIVE], from dart-io.RawSynchronousSocket.shutdown (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/io/sync_socket.dart:74:8)
 warning: unresolved doc reference [SEND], from dart-io.RawSynchronousSocket.shutdown (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/io/sync_socket.dart:74:8)
 warning: unresolved doc reference [ZLibDecoder.level], from dart-io.ZLibOption.DEFAULT_LEVEL (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/io/data_transformer.dart:35:20)
 warning: unresolved doc reference [ZLibDecoder.memLevel], from dart-io.ZLibOption.DEFAULT_MEM_LEVEL (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/io/data_transformer.dart:47:20)
 warning: unresolved doc reference [ZLibDecoder.level], from dart-io.ZLibOption.MAX_LEVEL (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/io/data_transformer.dart:31:20)
 warning: unresolved doc reference [ZLibDecoder.memLevel], from dart-io.ZLibOption.MAX_MEM_LEVEL (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/io/data_transformer.dart:43:20)
 warning: unresolved doc reference [ZLibDecoder.level], from dart-io.ZLibOption.MIN_LEVEL (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/io/data_transformer.dart:27:20)
 warning: unresolved doc reference [ZLibDecoder.memLevel], from dart-io.ZLibOption.MIN_MEM_LEVEL (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/io/data_transformer.dart:39:20)
generating docs for library dart:isolate from isolate.dart...
 warning: unresolved doc reference [errorAreFatal], from dart-isolate.Isolate.spawn (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/isolate/isolate.dart:227:35)
 warning: unresolved doc reference [errorAreFatal], from dart-isolate.Isolate.spawnUri (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/isolate/isolate.dart:309:35)
generating docs for library dart:math from math.dart...
generating docs for library dart:typed_data from typed_data.dart...
 warning: unresolved doc reference [test], from dart-typed_data.Float32List.any (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/core/iterable.dart:333:8)
 warning: unresolved doc reference [test], from dart-typed_data.Float32List.every (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/core/iterable.dart:294:8)
generating docs for library internal_style from internal_style.dart...
 warning: unresolved doc reference [parts], from internal_style.Style.relativePathToUri (file:///Users/devoncarew/.pub-cache/hosted/pub.dartlang.org/path-1.4.1/lib/src/style.dart:80:7)
generating docs for library logging from logging.dart...
 warning: logging has no library level documentation comments (file:///Users/devoncarew/.pub-cache/hosted/pub.dartlang.org/logging-0.11.3+1/lib/logging.dart:7:9)
 warning: unresolved doc reference [Handler], from logging.LogRecord (file:///Users/devoncarew/.pub-cache/hosted/pub.dartlang.org/logging-0.11.3+1/lib/logging.dart:339:7)
generating docs for library path from path.dart...
 warning: unresolved doc reference [root], from path.Context.relative (file:///Users/devoncarew/.pub-cache/hosted/pub.dartlang.org/path-1.4.1/lib/src/context.dart:440:10)
documented 13 libraries in 38.4 seconds

validating docs...
found 39 warnings and 0 errors

Success! Docs generated into /Users/devoncarew/projects/devoncarew/analysis_server_lib/doc/api

@jcollins-g

[devoncarew]

and before the change:

Generating documentation for 'analysis_server_lib' into /Users/devoncarew/projects/devoncarew/analysis_server_lib/doc/api/

parsing lib/analysis_server_lib.dart...
Parsed 14 files in 6.1 seconds.


generating docs for libraries analysis_server_lib, dart:async, dart:collection, dart:convert, dart:core, dart:developer, dart:io, dart:isolate, dart:math, dart:typed_data, internal_style, logging, path


documenting analysis_server_lib
generating docs for library analysis_server_lib from analysis_server_lib.dart...
generating docs for library dart:async from async.dart...
 warning: unresolved doc reference [Stream.groupByMapped], from dart-async.StreamGroup (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/async/stream.dart:1916:7)
 warning: unresolved doc reference [cleanup], from dart-async.Future.wait (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/async/future.dart:316:26)
 warning: unresolved doc reference [GroupBy], from dart-async.StreamGroup.values (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/async/stream.dart:1921:19)
generating docs for library dart:collection from collection.dart...
 warning: unresolved doc reference [contains], from dart-collection.MapBase (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/collection/maps.dart:23:16)
 warning: unresolved doc reference [contains], from dart-collection.MapMixin (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/collection/maps.dart:41:16)
 warning: unresolved doc reference [contains], from dart-collection.UnmodifiableMapBase (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/collection/maps.dart:103:16)
 warning: unresolved doc reference [test], from dart-collection.DoubleLinkedQueue.any (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/core/iterable.dart:333:8)
 warning: unresolved doc reference [test], from dart-collection.DoubleLinkedQueue.every (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/core/iterable.dart:294:8)
 warning: unresolved doc reference [test], from dart-collection.HashSet.any (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/core/iterable.dart:333:8)
 warning: unresolved doc reference [test], from dart-collection.HashSet.every (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/core/iterable.dart:294:8)
 warning: unresolved doc reference [test], from dart-collection.LinkedHashSet.any (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/core/iterable.dart:333:8)
 warning: unresolved doc reference [test], from dart-collection.LinkedHashSet.every (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/core/iterable.dart:294:8)
 warning: unresolved doc reference [a], from dart-collection.List.lastIndexOf (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/core/list.dart:278:7)
 warning: no canonical library found for dart-_internal.EfficientLengthIterable, not linking (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/internal/iterable.dart:11:16)
 warning: no canonical library found for dart-_internal.ListIterable, not linking (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/internal/iterable.dart:28:16)
 warning: unresolved doc reference [f], from dart-collection.Iterable.forEach (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/core/iterable.dart:225:8)
 warning: unresolved doc reference [test], from dart-collection.Queue.any (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/core/iterable.dart:333:8)
 warning: unresolved doc reference [test], from dart-collection.Queue.every (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/core/iterable.dart:294:8)
 warning: unresolved doc reference [value], from dart-collection.Set.add (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/core/set.dart:111:8)
 warning: unresolved doc reference [element], from dart-collection.Iterable.contains (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/core/iterable.dart:214:8)
 warning: unresolved doc reference [value], from dart-collection.Set.remove (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/core/set.dart:126:8)
 warning: no canonical library found for dart-_internal.UnmodifiableListBase, not linking (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/internal/list.dart:200:16)
generating docs for library dart:convert from convert.dart...
generating docs for library dart:core from core.dart...
generating docs for library dart:developer from developer.dart...
generating docs for library dart:io from io.dart...
 warning: unresolved doc reference [host], from dart-io.HttpClient.openUrl (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/io/http.dart:1377:29)
 warning: unresolved doc reference [RECEIVE], from dart-io.RawSynchronousSocket.shutdown (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/io/sync_socket.dart:74:8)
 warning: unresolved doc reference [SEND], from dart-io.RawSynchronousSocket.shutdown (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/io/sync_socket.dart:74:8)
 warning: unresolved doc reference [ZLibDecoder.level], from dart-io.ZLibOption.DEFAULT_LEVEL (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/io/data_transformer.dart:35:20)
 warning: unresolved doc reference [ZLibDecoder.memLevel], from dart-io.ZLibOption.DEFAULT_MEM_LEVEL (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/io/data_transformer.dart:47:20)
 warning: unresolved doc reference [ZLibDecoder.level], from dart-io.ZLibOption.MAX_LEVEL (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/io/data_transformer.dart:31:20)
 warning: unresolved doc reference [ZLibDecoder.memLevel], from dart-io.ZLibOption.MAX_MEM_LEVEL (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/io/data_transformer.dart:43:20)
 warning: unresolved doc reference [ZLibDecoder.level], from dart-io.ZLibOption.MIN_LEVEL (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/io/data_transformer.dart:27:20)
 warning: unresolved doc reference [ZLibDecoder.memLevel], from dart-io.ZLibOption.MIN_MEM_LEVEL (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/io/data_transformer.dart:39:20)
generating docs for library dart:isolate from isolate.dart...
 warning: unresolved doc reference [errorAreFatal], from dart-isolate.Isolate.spawn (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/isolate/isolate.dart:227:35)
 warning: unresolved doc reference [errorAreFatal], from dart-isolate.Isolate.spawnUri (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/isolate/isolate.dart:309:35)
generating docs for library dart:math from math.dart...
generating docs for library dart:typed_data from typed_data.dart...
 warning: unresolved doc reference [test], from dart-typed_data.Float32List.any (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/core/iterable.dart:333:8)
 warning: unresolved doc reference [test], from dart-typed_data.Float32List.every (file:///usr/local/Cellar/dart/1.24.0-dev.4.0/libexec/lib/core/iterable.dart:294:8)
generating docs for library internal_style from internal_style.dart...
 warning: unresolved doc reference [parts], from internal_style.Style.relativePathToUri (file:///Users/devoncarew/.pub-cache/hosted/pub.dartlang.org/path-1.4.1/lib/src/style.dart:80:7)
generating docs for library logging from logging.dart...
 warning: logging has no library level documentation comments (file:///Users/devoncarew/.pub-cache/hosted/pub.dartlang.org/logging-0.11.3+1/lib/logging.dart:7:9)
 warning: unresolved doc reference [Handler], from logging.LogRecord (file:///Users/devoncarew/.pub-cache/hosted/pub.dartlang.org/logging-0.11.3+1/lib/logging.dart:339:7)
generating docs for library path from path.dart...
 warning: unresolved doc reference [root], from path.Context.relative (file:///Users/devoncarew/.pub-cache/hosted/pub.dartlang.org/path-1.4.1/lib/src/context.dart:440:10)
validating docs
Documented 13 libraries in 63.1 seconds.
Finished with:  39 warnings, 0 errors

Success! Docs generated into /Users/devoncarew/projects/devoncarew/analysis_server_lib/doc/api

[jcollins-g]

This LGTM, but how well does the new change work with --show-progress? Some of the weirdness we do is to try to make things look OK with both.

[devoncarew]

Yup, this changes to end messages with newlines instead of start them w/ newlines. One way we lead with dots, one we trail.

I see --show-progress as being useful for CI, where you want to print something periodically. I think a next step in terms of showing progress would be to use some ansi codes to show indeterminate progress.

[jcollins-g]

Sounds good.

[jcollins-g]

this PR has made --show-progress pretty ugly, I'm going to revert it.

[jcollins-g]

an example of the output ugliness I wanted to avoid. I now recognize this is what you meant by "leading with dots".

[devoncarew]

I don't believe that --show-progress is generally user-facing - more for CI - but if you want to revert that is your call. There were other changes in here we do want to keep however, re: making the output a bit more consistent.