[vm/ffi] Work around dartdoc crash to fix API doc generation

Issue: #38786

Change-Id: Ida4bb78da1aabdf6da259e0d66840d9db4b1428d
Cq-Include-Trybots: luci.dart.try:dart-sdk-linux-try
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/120788
Commit-Queue: Daco Harkes <dacoharkes@google.com>
Reviewed-by: Martin Kustermann <kustermann@google.com>

Author: dcharkes

runtime/tools/ffi/sdk_lib_ffi_generator.dart

@@ -73,11 +73,11 @@ void generateHeader(StringBuffer buffer) {
 void generatePublicExtension(
     StringBuffer buffer, String nativeType, String dartType) {
   final storeTrunctateInt = """
-  /// Note that ints which do not fit in [$nativeType] are truncated.
+  /// Note that ints which do not fit in `$nativeType` are truncated.
 """;
 
   final storeTrunctateDouble = """
-  /// Note that doubles stored into Pointer<[Float]> lose precision.
+  /// Note that doubles stored into Pointer<`Float`> lose precision.
 """;
 
   final storeTruncate =
@@ -89,35 +89,37 @@ void generatePublicExtension(
 
   final loadSignExtend = isInt(nativeType) ? loadSignExtendInt : "";
 
+  // TODO(dartdoc-bug): Use [] instead of ``, once issue
+  // https://github.com/dart-lang/dartdoc/issues/2039 is fixed.
   buffer.write("""
 /// Extension on [Pointer] specialized for the type argument [$nativeType].
 extension ${nativeType}Pointer on Pointer<$nativeType> {
   /// Load a Dart value from this location.
   ///
   /// The value is automatically unmarshalled from its native representation.
 $loadSignExtend  ///
-  /// Note that [address] needs to be aligned to the size of [$nativeType].
+  /// Note that `address` needs to be aligned to the size of `$nativeType`.
   external $dartType get value;
 
   /// Store a Dart value into this location.
   ///
-  /// The [value] is automatically marshalled into its native representation.
+  /// The `value` is automatically marshalled into its native representation.
 $storeTruncate  ///
-  /// Note that [address] needs to be aligned to the size of [$nativeType].
+  /// Note that `address` needs to be aligned to the size of `$nativeType`.
   external void set value($dartType value);
 
-  /// Load a Dart value from this location offset by [index].
+  /// Load a Dart value from this location offset by `index`.
   ///
   /// The value is automatically unmarshalled from its native representation.
 $loadSignExtend  ///
-  /// Note that [address] needs to be aligned to the size of [$nativeType].
+  /// Note that `address` needs to be aligned to the size of `$nativeType`.
   external $dartType operator [](int index);
 
-  /// Store a Dart value into this location offset by [index].
+  /// Store a Dart value into this location offset by `index`.
   ///
-  /// The [value] is automatically marshalled into its native representation.
+  /// The `value` is automatically marshalled into its native representation.
 $storeTruncate  ///
-  /// Note that [address] needs to be aligned to the size of [$nativeType].
+  /// Note that `address` needs to be aligned to the size of `$nativeType`.
   external void operator []=(int index, $dartType value);
 }