From fab8f03740c7521118806c6c367488016dea1151 Mon Sep 17 00:00:00 2001
From: harukasan <harukasan@pixiv.com>
Date: Fri, 9 Jan 2015 18:01:51 +0900
Subject: [PATCH] Update comments

---
 examples/decode/decode.go |  1 +
 examples/encode/encode.go |  1 +
 webp/decode.go            | 28 +++++++++++++++-------------
 webp/webp.go              |  4 +++-
 webp/yuva_image.go        | 10 ++++++++--
 5 files changed, 28 insertions(+), 16 deletions(-)

diff --git a/examples/decode/decode.go b/examples/decode/decode.go
index 24a393d..3a46724 100644
--- a/examples/decode/decode.go
+++ b/examples/decode/decode.go
@@ -1,3 +1,4 @@
+// Package main is an example implementation of WebP decoder.
 package main
 
 import (
diff --git a/examples/encode/encode.go b/examples/encode/encode.go
index 04383ae..de6c484 100644
--- a/examples/encode/encode.go
+++ b/examples/encode/encode.go
@@ -1,3 +1,4 @@
+// Package main is an example implementation of WebP encoder.
 package main
 
 import (
diff --git a/webp/decode.go b/webp/decode.go
index ef7b227..46cf7ca 100644
--- a/webp/decode.go
+++ b/webp/decode.go
@@ -17,19 +17,20 @@ import (
 	"unsafe"
 )
 
-// DecoderOptions specifies decoding options
+// DecoderOptions specifies decoding options of WebP.
 type DecoderOptions struct {
-	BypassFiltering        bool
-	NoFancyUpsampling      bool
-	Crop                   image.Rectangle
-	Scale                  image.Rectangle
-	UseThreads             bool
-	DitheringStrength      int
-	Flip                   bool
-	AlphaDitheringStrength int
+	BypassFiltering        bool            // If true, bypass filtering process
+	NoFancyUpsampling      bool            // If true, do not fancy upsampling
+	Crop                   image.Rectangle // Do cropping if image.Rectangle is not empty.
+	Scale                  image.Rectangle // Do scaling if image.Rectangle is not empty.
+	UseThreads             bool            // If true, use multi threads
+	DitheringStrength      int             // Specify dithering strength [0=Off .. 100=full]
+	Flip                   bool            // If true, flip output vertically
+	AlphaDitheringStrength int             // Specify alpha dithering strength in [0..100]
 }
 
-// BitstreamFeatures retrived from data stream.
+// BitstreamFeatures represents the image properties which are retrived from
+// data stream.
 type BitstreamFeatures struct {
 	Width                 int  // Image width in pixels
 	Height                int  // Image height in pixles
@@ -52,7 +53,7 @@ func GetInfo(data []byte) (width, height int) {
 	return int(w), int(h)
 }
 
-// GetFeatures returns features retrived from data stream.
+// GetFeatures returns features as BitstreamFeatures retrived from data stream.
 func GetFeatures(data []byte) (f *BitstreamFeatures, err error) {
 	var cf C.WebPBitstreamFeatures
 	status := C.WebPGetFeatures((*C.uint8_t)(&data[0]), (C.size_t)(len(data)), &cf)
@@ -72,7 +73,8 @@ func GetFeatures(data []byte) (f *BitstreamFeatures, err error) {
 	return
 }
 
-// DecodeYUVA decodes WebP image into YUV image with alpha channel.
+// DecodeYUVA decodes WebP image into YUV image with alpha channel, and returns
+// it as *YUVAImage.
 func DecodeYUVA(data []byte, options *DecoderOptions) (img *YUVAImage, err error) {
 	config, err := initDecoderConfig(options)
 	if err != nil {
@@ -127,7 +129,7 @@ func DecodeYUVA(data []byte, options *DecoderOptions) (img *YUVAImage, err error
 	return
 }
 
-// DecodeRGBA decodes WebP image into RGBA image.
+// DecodeRGBA decodes WebP image into RGBA image and returns it as an *image.RGBA.
 func DecodeRGBA(data []byte, options *DecoderOptions) (img *image.RGBA, err error) {
 	config, err := initDecoderConfig(options)
 	if err != nil {
diff --git a/webp/webp.go b/webp/webp.go
index 78dea82..2e09c7e 100644
--- a/webp/webp.go
+++ b/webp/webp.go
@@ -1,3 +1,5 @@
+// Package webp provides an interface to libwebp library to decoding/encoding
+// WebP image.
 package webp
 
 /*
@@ -19,7 +21,7 @@ const (
 	YUV420A ColorSpace = C.WEBP_YUV420A
 )
 
-// Preset corresponds to C.WebPPreset
+// Preset corresponds to C.WebPPreset.
 type Preset int
 
 const (
diff --git a/webp/yuva_image.go b/webp/yuva_image.go
index 171665e..6f98738 100644
--- a/webp/yuva_image.go
+++ b/webp/yuva_image.go
@@ -4,10 +4,16 @@ import "image"
 
 // YUVAImage represents a image of YUV colors with alpha channel image.
 //
-// We can not insert WebP planer image into image.YCbCr,
-// because image.YCbCr is not compatible with ITU-R BT.601, but JFIF/JPEG one.
+// YUVAImage contains decoded YCbCr image data with alpha channel,
+// but it is not compatible with image.YCbCr. Because, the RGB-YCbCr conversion
+// that used in WebP is following to ITU-R BT.601 standard.
+// In contrast, the conversion of Image.YCbCr (and color.YCbCrModel) is following
+// to the JPEG standard (JFIF). If you need the image as image.YCBCr, you will
+// first convert from WebP to RGB image, then convert from RGB image to JPEG's
+// YCbCr image.
 //
 // See: http://en.wikipedia.org/wiki/YCbCr
+//
 type YUVAImage struct {
 	Y, Cb, Cr, A []uint8
 	YStride      int