Update starboard media header description

This PR updates the description in drm.h, decode_target.h, media.h, and player.h.

b/326450058

starboard/decode_target.h

@@ -165,11 +165,11 @@ typedef void (*SbDecodeTargetGlesContextRunner)(
 typedef struct SbDecodeTargetGraphicsContextProvider {
   // A reference to the EGLDisplay object that hosts the EGLContext that will
   // be used to render any produced SbDecodeTargets.  Note that it has the
-  // type |void*| in order to avoid #including the EGL header files here.
+  // type |void*| in order to avoid including the EGL header files here.
   void* egl_display;
   // The EGLContext object that will be used to render any produced
   // SbDecodeTargets.  Note that it has the
-  // type |void*| in order to avoid #including the EGL header files here.
+  // type |void*| in order to avoid including the EGL header files here.
   void* egl_context;
 
   // The |gles_context_runner| function pointer is passed in from the
@@ -252,7 +252,7 @@ typedef struct SbDecodeTargetInfo {
   int height;
 
   // The image planes (e.g. kSbDecodeTargetPlaneRGBA, or {kSbDecodeTargetPlaneY,
-  //  kSbDecodeTargetPlaneU, kSbDecodeTargetPlaneV} associated with this
+  // kSbDecodeTargetPlaneU, kSbDecodeTargetPlaneV}) associated with this
   // decode target.
   SbDecodeTargetInfoPlane planes[3];
 } SbDecodeTargetInfo;
@@ -300,7 +300,7 @@ static inline int SbDecodeTargetNumberOfPlanesForFormat(
 // This function will likely result in the destruction of the SbDecodeTarget and
 // all its associated surfaces, though in some cases, platforms may simply
 // adjust a reference count.  This function must be called on a thread with
-// the context
+// the context.
 SB_EXPORT void SbDecodeTargetRelease(SbDecodeTarget decode_target);
 
 // Writes all information about |decode_target| into |out_info|.
@@ -312,7 +312,7 @@ SB_EXPORT bool SbDecodeTargetGetInfo(SbDecodeTarget decode_target,
 
 // Inline convenience function to run an arbitrary
 // SbDecodeTargetGlesContextRunnerTarget function through a
-// SbDecodeTargetGraphicsContextProvider.  This is intended to be called by
+// SbDecodeTargetGraphicsContextProvider. This is intended to be called by
 // Starboard implementations, if it is necessary.
 static inline void SbDecodeTargetRunInGlesContext(
     SbDecodeTargetGraphicsContextProvider* provider,

starboard/drm.h

@@ -48,13 +48,13 @@ typedef enum SbDrmStatus {
   kSbDrmStatusNotSupportedError,
   kSbDrmStatusInvalidStateError,
   kSbDrmStatusQuotaExceededError,
-  // The following error can be used when the error status cannot be mapped to
-  // one of the above errors.
+  // The kSbDrmStatusUnknownError can be used when the error status cannot be
+  // mapped to one of the rest errors.
   kSbDrmStatusUnknownError,
 } SbDrmStatus;
 
 // Status of a particular media key.
-// https://w3c.github.io/encrypted-media/#idl-def-MediaKeyStatus
+// https://www.w3.org/TR/encrypted-media/#idl-def-mediakeystatus
 typedef enum SbDrmKeyStatus {
   kSbDrmKeyStatusUsable,
   kSbDrmKeyStatusExpired,
@@ -180,8 +180,14 @@ typedef void (*SbDrmSessionUpdatedFunc)(SbDrmSystem drm_system,
                                         int session_id_size);
 
 // A callback for notifications that the status of one or more keys in a session
-// has been changed.  All keys of the session and their new status will be
-// passed along.  Any keys not in the list is considered as deleted.
+// has been changed.  All keys |key_ids| of the session and their new status
+// will be passed along.  Any keys not in the list are considered as deleted.
+//
+// |number_of_keys| is the number of keys.
+//
+// |key_ids| is a pointer of a vector contains keys.
+//
+// |key_statuses| is a pointer of a vector contains the status of each key.
 typedef void (*SbDrmSessionKeyStatusesChangedFunc)(
     SbDrmSystem drm_system,
     void* context,
@@ -191,7 +197,7 @@ typedef void (*SbDrmSessionKeyStatusesChangedFunc)(
     const SbDrmKeyId* key_ids,
     const SbDrmKeyStatus* key_statuses);
 
-// A callback for signalling that a session has been closed by the SbDrmSystem
+// A callback for signalling that a session has been closed by the SbDrmSystem.
 typedef void (*SbDrmSessionClosedFunc)(SbDrmSystem drm_system,
                                        void* context,
                                        const void* session_id,
@@ -294,9 +300,11 @@ SB_EXPORT SbDrmSystem SbDrmCreateSystem(
 // used.
 //
 // |type|: The case-sensitive type of the session update request payload. Must
-//   not be NULL.
+// not be NULL.
+//
 // |initialization_data|: The data for which the session update
-//   request payload is created. Must not be NULL.
+// request payload is created. Must not be NULL.
+//
 // |initialization_data_size|: The size of the session update request payload.
 SB_EXPORT void SbDrmGenerateSessionUpdateRequest(
     SbDrmSystem drm_system,
@@ -353,14 +361,17 @@ SB_EXPORT bool SbDrmIsServerCertificateUpdatable(SbDrmSystem drm_system);
 // |SbDrmIsServerCertificateUpdatable| is called first and returned true.
 //
 // |drm_system|: The DRM system whose server certificate is being updated. Must
-//   not be |kSbDrmSystemInvalid|.
+// not be |kSbDrmSystemInvalid|.
+//
 // |ticket|: The opaque ID that allows to distinguish callbacks from multiple
-//   concurrent calls to SbDrmUpdateServerCertificate(), which will be passed to
-//   |server_certificate_updated_callback| as-is. It is the responsibility of
-//   the caller to establish ticket uniqueness, issuing multiple requests with
-//   the same ticket may result in undefined behavior. The value
-//   |kSbDrmTicketInvalid| must not be used.
+// concurrent calls to SbDrmUpdateServerCertificate(), which will be passed to
+// |server_certificate_updated_callback| as-is. It is the responsibility of
+// the caller to establish ticket uniqueness, issuing multiple requests with
+// the same ticket may result in undefined behavior. The value
+// |kSbDrmTicketInvalid| must not be used.
+//
 // |certificate|: Pointer to the server certificate data. Must not be NULL.
+//
 // |certificate_size|: Size of the server certificate data.
 SB_EXPORT void SbDrmUpdateServerCertificate(SbDrmSystem drm_system,
                                             int ticket,