add docs, remove dead code

analysis_options.yaml

@@ -142,6 +142,7 @@ linter:
     - sort_pub_dependencies
     - sort_unnamed_constructors_first
     - super_goes_last
+    - public_member_api_docs
     - test_types_in_equals
     - throw_in_finally
     # - type_annotate_public_apis # subset of always_specify_types

lib/avd.dart

@@ -1,3 +1,4 @@
+// ignore_for_file: public_member_api_docs
 import 'dart:async';
 import 'dart:convert';
 import 'dart:typed_data';

lib/parser.dart

@@ -5,7 +5,11 @@ import 'package:xml/xml.dart' show XmlPushReader;
 import 'src/svg/parser_state.dart';
 import 'src/vector_drawable.dart';
 
+/// Parses SVG data into a [DrawableRoot].
 class SvgParser {
+  /// Parses SVG from a string to a [DrawableRoot].
+  ///
+  /// The [key] parameter is used for debugging purposes.
   Future<DrawableRoot> parse(String str, {String key}) async {
     return await SvgParserState(XmlPushReader(str), key).parse();
   }

lib/src/avd/xml_parsers.dart

@@ -1,3 +1,4 @@
+// ignore_for_file: public_member_api_docs
 import 'dart:math';
 import 'dart:ui';
 
@@ -8,6 +9,7 @@ import 'package:xml/xml.dart';
 import '../svg/colors.dart';
 import '../utilities/xml.dart';
 
+/// The AVD namespace.
 const String androidNS = 'http://schemas.android.com/apk/res/android';
 
 /// Parses an AVD @android:viewportWidth and @android:viewportHeight attributes to a [Rect].

lib/src/avd_parser.dart

@@ -1,3 +1,4 @@
+// ignore_for_file: public_member_api_docs
 import 'dart:ui';
 
 import 'package:xml/xml.dart';

lib/src/picture_cache.dart

@@ -2,6 +2,7 @@ import 'picture_stream.dart';
 
 const int _kDefaultSize = 1000;
 
+/// A cache for [Picture] objects.
 // TODO(dnfield): Implement memory based limiting, once `approximateByteCount` is exposed in engine
 class PictureCache {
   final Map<Object, PictureStreamCompleter> _cache =

lib/src/picture_provider.dart

@@ -398,6 +398,7 @@ abstract class AssetBundlePictureProvider
   /// const constructors so that they can be used in const expressions.
   const AssetBundlePictureProvider(this.decoder) : assert(decoder != null);
 
+  /// The decoder to use to turn a string into a [PictureInfo] object.
   final PictureInfoDecoder<String> decoder;
 
   /// Converts a key into an [PictureStreamCompleter], and begins fetching the
@@ -443,6 +444,7 @@ class NetworkPicture extends PictureProvider<NetworkPicture> {
   const NetworkPicture(this.decoder, this.url, {this.headers, this.colorFilter})
       : assert(url != null);
 
+  /// The decoder to use to turn a [Uint8List] into a [PictureInfo] object.
   final PictureInfoDecoder<Uint8List> decoder;
 
   /// The URL from which the picture will be fetched.
@@ -616,6 +618,18 @@ class MemoryPicture extends PictureProvider<MemoryPicture> {
   String toString() => '$runtimeType(${describeIdentity(bytes)})';
 }
 
+/// Decodes the given [String] as a picture, associating it with the
+/// given scale.
+///
+/// The provided [String] should not be changed after it is provided
+/// to a [StringPicture]. To provide an [PictureStream] that represents a picture
+/// that changes over time, consider creating a new subclass of [PictureProvider]
+/// whose [load] method returns a subclass of [PictureStreamCompleter] that can
+/// handle providing multiple pictures.
+///
+/// See also:
+///
+///  * [SvgPicture.string] for a shorthand of an [SvgPicture] widget backed by [StringPicture].
 class StringPicture extends PictureProvider<StringPicture> {
   /// Creates an object that decodes a [Uint8List] buffer as a picture.
   ///

lib/src/picture_stream.dart

@@ -14,6 +14,7 @@ typedef ViewportCalculator = Rect Function(double devicePixelRatio);
 /// Represents information about a ui.Picture to be drawn on a canvas.
 @immutable
 class PictureInfo {
+  /// Creates a new PictureInfo object.
   const PictureInfo({
     @required this.picture,
     @required this.viewport,

lib/src/render_picture.dart

@@ -6,18 +6,26 @@ import 'package:meta/meta.dart';
 
 import 'picture_stream.dart';
 
+/// A widget that displays a [dart:ui.Picture] directly.
 @immutable
 class RawPicture extends LeafRenderObjectWidget {
+  /// Creates a new [RawPicture] object.
   const RawPicture(
     this.picture, {
     Key key,
     this.matchTextDirection = false,
     this.allowDrawingOutsideViewBox = false,
   }) : super(key: key);
 
+  /// The picture to paint.
   final PictureInfo picture;
+
+  /// Whether this picture should match the ambient [TextDirection] or not.
   final bool matchTextDirection;
 
+  /// Whether to allow this picture to draw outside of its specified
+  /// [PictureInfo.viewport]. Caution should be used here, as this may lead to
+  /// greater memory usage than intended.
   final bool allowDrawingOutsideViewBox;
 
   @override
@@ -57,6 +65,7 @@ class RawPicture extends LeafRenderObjectWidget {
 /// flag should be used with care, as it may result in unexpected effects or
 /// additional memory usage.
 class RenderPicture extends RenderBox {
+  /// Creates a new [RenderPicture].
   RenderPicture({
     PictureInfo picture,
     bool matchTextDirection = false,
@@ -131,8 +140,9 @@ class RenderPicture extends RenderBox {
     markNeedsPaint();
   }
 
-  PictureInfo _picture;
+  /// The information about the picture to draw.
   PictureInfo get picture => _picture;
+  PictureInfo _picture;
   set picture(PictureInfo val) {
     if (val == picture) {
       return;
@@ -141,8 +151,13 @@ class RenderPicture extends RenderBox {
     markNeedsPaint();
   }
 
-  bool _allowDrawingOutsideViewBox;
+  /// Whether to allow the rendering of this picture to exceed the
+  /// [PictureInfo.viewport] bounds.
+  ///
+  /// Caution should be used around setting this parameter to true, as it
+  /// may result in greater memory usage during rasterization.
   bool get allowDrawingOutsideViewBox => _allowDrawingOutsideViewBox;
+  bool _allowDrawingOutsideViewBox;
   set allowDrawingOutsideViewBox(bool val) {
     if (val == _allowDrawingOutsideViewBox) {
       return;
@@ -204,6 +219,8 @@ class RenderPicture extends RenderBox {
   }
 }
 
+/// Scales a [Canvas] to a given [viewBox] based on the [desiredSize]
+/// of the widget.
 void scaleCanvasToViewBox(
   Canvas canvas,
   Size desiredSize,

lib/src/svg/colors.dart

@@ -1,5 +1,6 @@
 import 'dart:ui';
 
+/// The color black, with full opacity.
 const Color colorBlack = Color(0xFF000000);
 
 /// Converts a SVG Color String (either a # prefixed color string or a named color) to a [Color].