[RemoteMirror] Add comments to the new APIs and types.

rdar://problem/55481578

Author: mikeash

include/swift/SwiftRemoteMirror/SwiftRemoteMirror.h

@@ -288,6 +288,15 @@ SWIFT_REMOTE_MIRROR_LINKAGE
 size_t swift_reflection_demangle(const char *MangledName, size_t Length,
                                  char *OutDemangledName, size_t MaxLength);
 
+/// Iterate over the process's protocol conformance cache.
+///
+/// Calls the passed in Call function for each protocol conformance found in
+/// the conformance cache. The function is passed the type which conforms and
+/// the protocol it conforms to. The ContextPtr is passed through unchanged.
+///
+/// Returns NULL on success. On error, returns a pointer to a C string
+/// describing the error. This pointer remains valid until the next
+/// swift_reflection call on the given context.
 SWIFT_REMOTE_MIRROR_LINKAGE
 const char *swift_reflection_iterateConformanceCache(
   SwiftReflectionContextRef ContextRef,
@@ -296,13 +305,27 @@ const char *swift_reflection_iterateConformanceCache(
                void *ContextPtr),
   void *ContextPtr);
 
+/// Iterate over the process's metadata allocations.
+///
+/// Calls the passed in Call function for each metadata allocation. The function
+/// is passed a structure that describes the allocation. The ContextPtr is
+/// passed through unchanged.
+///
+/// Returns NULL on success. On error, returns a pointer to a C string
+/// describing the error. This pointer remains valid until the next
+/// swift_reflection call on the given context.
 SWIFT_REMOTE_MIRROR_LINKAGE
 const char *swift_reflection_iterateMetadataAllocations(
   SwiftReflectionContextRef ContextRef,
   void (*Call)(swift_metadata_allocation_t Allocation,
                void *ContextPtr),
   void *ContextPtr);
 
+/// Given a metadata allocation, return the metadata it points to. Returns NULL
+/// on failure. Despite the name, not all allocations point to metadata.
+/// Currently, this will return a metadata only for allocations with tag
+/// SWIFT_GENERIC_METADATA_CACHE_ALLOCATION. Support for additional tags may be
+/// added in the future. The caller must gracefully handle failure.
 SWIFT_REMOTE_MIRROR_LINKAGE
 swift_reflection_ptr_t swift_reflection_allocationMetadataPointer(
   SwiftReflectionContextRef ContextRef,

include/swift/SwiftRemoteMirror/SwiftRemoteMirrorTypes.h

@@ -145,13 +145,19 @@ enum swift_metadata_allocation_tag {
   SWIFT_GENERIC_METADATA_CACHE_ALLOCATION = 14,
 };
 
-// Tags other than those defined in swift_metadata_allocation_tag will be used
-// and must be treated as unknown.
 typedef int swift_metadata_allocation_tag_t;
 
+/// A metadata allocation made by the Swift runtime.
 typedef struct swift_metadata_allocation {
+  /// The allocation's tag, which describes what kind of allocation it is. This
+  /// may be one of the values in swift_metadata_allocation_tag, or something
+  /// else, in which case the tag should be considered unknown.
   swift_metadata_allocation_tag_t Tag;
+
+  /// A pointer to the start of the allocation in the remote process.
   swift_reflection_ptr_t Ptr;
+
+  /// The size of the allocation in bytes.
   unsigned Size;
 } swift_metadata_allocation_t;