genai: improve file upload doc (#183)

For #180.

genai/config.yaml

@@ -64,10 +64,16 @@ types:
       fields:
         MimeType:
           name: MIMEType
+          doc: |
+            The IANA standard MIME type of the source data.
+            If present, this overrides the MIME type specified or inferred
+            when the file was uploaded.
+            The supported MIME types are documented on [this page].
+            
+            [this page]: https://ai.google.dev/gemini-api/docs/prompting_with_media?lang=go#supported_file_formats
         FileUri:
           name: URI
-          # TODO(jba): support field doc in protoveneer
-          # doc: 'The URI returned from UploadFile or GetFile.'
+          doc: 'The URI returned from UploadFile or GetFile.'
 
     GenerationConfig:
       fields:

genai/files.go

@@ -30,16 +30,27 @@ import (
 
 // UploadFileOptions are options for [Client.UploadFile].
 type UploadFileOptions struct {
-	DisplayName string // a more readable name for the file
-	MIMEType    string // the MIME type of the file; if omitted, it will be inferred
+	// A more readable name for the file.
+	DisplayName string
+
+	// The IANA standard MIME type of the file. It will be stored with the file as metadata.
+	// If omitted, the service will try to infer it. You may instead wish to use
+	// [http.DetectContentType].
+	// The supported MIME types are documented on [this page].
+	//
+	// [this page]: https://ai.google.dev/gemini-api/docs/prompting_with_media?lang=go#supported_file_formats
+	MIMEType string
 }
 
 // UploadFile copies the contents of the given io.Reader to file storage associated
 // with the service, and returns information about the resulting file.
 //
-// The name may be empty, in which case a unique name will be generated.
+// The name is a relatively short, unique identifier for the file (rather than a typical
+// filename).
+// Typically it should be left empty, in which case a unique name will be generated.
 // Otherwise, it can contain up to 40 characters that are lowercase
 // alphanumeric or dashes (-), not starting or ending with a dash.
+// To generate your own unique names, consider a cryptographic hash algorithm like SHA-1.
 // The string "files/" is prepended to the name if it does not contain a '/'.
 //
 // Use the returned file's URI field with a [FileData] Part to use it for generation.

genai/generativelanguagepb_veneer.gen.go

@@ -676,9 +676,14 @@ func (File) fromProto(p *pb.File) *File {
 
 // FileData is URI based data.
 type FileData struct {
-	// Optional. The IANA standard MIME type of the source data.
+	// The IANA standard MIME type of the source data.
+	// If present, this overrides the MIME type specified or inferred
+	// when the file was uploaded.
+	// The supported MIME types are documented on [this page].
+	//
+	// [this page]: https://ai.google.dev/gemini-api/docs/prompting_with_media?lang=go#supported_file_formats
 	MIMEType string
-	// Required. URI.
+	// The URI returned from UploadFile or GetFile.
 	URI string
 }