[ffi] Tweak the docs (dart-archive/ffi#63)

Be consistent about zero- vs. null-terminated (the latter was more
commonly used, but using the former was suggested in dart-archive/ffi#61). Furthermore,
align UTF-8/16 spelling and fix a couple of minor typos and formatting
issues.

Author: jpnurmi

pkgs/ffi/README.md

@@ -1,7 +1,7 @@
 [![Build Status](https://travis-ci.org/dart-lang/ffi.svg?branch=master)](https://travis-ci.org/dart-lang/ffi)
 
 Utilities for working with Foreign Function Interface (FFI) code, incl.
-converting between Dart strings and C strings encoded with utf8 and utf16.
+converting between Dart strings and C strings encoded with UTF-8 and UTF-16.
 
 For additional details about Dart FFI (`dart:ffi`), see
 https://dart.dev/guides/libraries/c-interop.

pkgs/ffi/example/main.dart

@@ -9,7 +9,7 @@ void main() {
   print(pointer.value);
   free(pointer);
 
-  // Use the Utf8 helper to encode null-terminated Utf8 strings in native memory.
+  // Use the Utf8 helper to encode zero-terminated UTF-8 strings in native memory.
   final String myString = '😎👿💬';
   final Pointer<Utf8> charPointer = Utf8.toUtf8(myString);
   print('First byte is: ${charPointer.cast<Uint8>().value}');

pkgs/ffi/lib/src/utf16.dart

@@ -8,21 +8,21 @@ import 'dart:typed_data';
 
 import 'package:ffi/ffi.dart';
 
-/// [Utf16] implements conversion between Dart strings and null-terminated
+/// [Utf16] implements conversion between Dart strings and zero-terminated
 /// UTF-16 encoded "char*" strings in C.
 ///
-/// [Utf16] is respresented as a struct so that `Pointer<Utf16>` can be used in
+/// [Utf16] is represented as a struct so that `Pointer<Utf16>` can be used in
 /// native function signatures.
 class Utf16 extends Struct {
-  /// Convert a [String] to a Utf16-encoded null-terminated C string.
+  /// Convert a [String] to a UTF-16 encoded zero-terminated C string.
   ///
-  /// If 'string' contains NULL bytes, the converted string will be truncated
+  /// If [string] contains NULL characters, the converted string will be truncated
   /// prematurely. Unpaired surrogate code points in [string] will be preserved
-  /// in the UTF-8 encoded result. See [Utf8Encoder] for details on encoding.
+  /// in the UTF-16 encoded result. See [Utf16Encoder] for details on encoding.
   ///
   /// Returns a malloc-allocated pointer to the result.
-  static Pointer<Utf16> toUtf16(String s) {
-    final units = s.codeUnits;
+  static Pointer<Utf16> toUtf16(String string) {
+    final units = string.codeUnits;
     final Pointer<Uint16> result = allocate<Uint16>(count: units.length + 1);
     final Uint16List nativeString = result.asTypedList(units.length + 1);
     nativeString.setAll(0, units);

pkgs/ffi/lib/src/utf8.dart

@@ -12,17 +12,17 @@ const int _kMaxSmi64 = (1 << 62) - 1;
 const int _kMaxSmi32 = (1 << 30) - 1;
 final int _maxSize = sizeOf<IntPtr>() == 8 ? _kMaxSmi64 : _kMaxSmi32;
 
-/// [Utf8] implements conversion between Dart strings and null-terminated
-/// Utf8-encoded "char*" strings in C.
+/// [Utf8] implements conversion between Dart strings and zero-terminated
+/// UTF-8 encoded "char*" strings in C.
 ///
-/// [Utf8] is respresented as a struct so that `Pointer<Utf8>` can be used in
+/// [Utf8] is represented as a struct so that `Pointer<Utf8>` can be used in
 /// native function signatures.
 //
 // TODO(https://github.com/dart-lang/ffi/issues/4): No need to use
 // 'asTypedList' when Pointer operations are performant.
 class Utf8 extends Struct {
-  /// Returns the length of a null-terminated string -- the number of (one-byte)
-  /// characters before the first null byte.
+  /// Returns the length of a zero-terminated string &mdash; the number of
+  /// bytes before the first zero byte.
   static int strlen(Pointer<Utf8> string) {
     final Pointer<Uint8> array = string.cast<Uint8>();
     final Uint8List nativeString = array.asTypedList(_maxSize);
@@ -42,9 +42,9 @@ class Utf8 extends Struct {
         string.cast<Uint8>().asTypedList(length).buffer, 0, length));
   }
 
-  /// Convert a [String] to a Utf8-encoded null-terminated C string.
+  /// Convert a [String] to a UTF-8 encoded zero-terminated C string.
   ///
-  /// If 'string' contains NULL bytes, the converted string will be truncated
+  /// If [string] contains NULL characters, the converted string will be truncated
   /// prematurely. Unpaired surrogate code points in [string] will be encoded
   /// as replacement characters (U+FFFD, encoded as the bytes 0xEF 0xBF 0xBD)
   /// in the UTF-8 encoded result. See [Utf8Encoder] for details on encoding.