Improve types/documentation.

Signed-off-by: Eric Peterson <ericpeterson@spotify.com>

packages/techdocs-common/src/stages/publish/types.ts

@@ -32,13 +32,19 @@ export type PublishRequest = {
   directory: string;
 };
 
-/* `remoteUrl` is the URL which serves files from the local publisher's static directory. */
+/**
+ * Response containing metadata about where files were published and what may
+ * have been published or updated.
+ */
 export type PublishResponse = {
+  /**
+   * The URL which serves files from the local publisher's static directory.
+   */
   remoteUrl?: string;
   /**
    * The list of objects (specifically their paths) that were published.
-   * Objects should not have a preceding slash, and should match how one would
-   * load the object over the `/static/docs/` TechDocs Backend Plugin endpoint.
+   * Objects do not have a preceding slash, and match how one would load the
+   * object over the `/static/docs/*` TechDocs Backend Plugin endpoint.
    */
   objects?: string[];
 } | void;