doc: Improve comments

ebitenutil/doc.go

@@ -0,0 +1,16 @@
+// Copyright 2017 The Ebiten Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Package ebitenutil provides utility functions for Ebiten.
+package ebitenutil

ebitenutil/file.go

@@ -25,7 +25,7 @@ import (
 
 // OpenFile opens a file and returns a stream for its data.
 //
-// This function is available both on desktops and browsers.
+// How to solve path depends on your environment. This varies on your desktop or web browser.
 // Note that this doesn't work on mobiles.
 func OpenFile(path string) (ReadSeekCloser, error) {
 	return os.Open(path)

ebitenutil/gif.go

@@ -104,6 +104,8 @@ func (r *recorder) update(screen *ebiten.Image) error {
 	return nil
 }
 
+// RecordScreenAsGIF is deprecated as of version 1.6.0-alpha.
+//
 // RecordScreenAsGIF returns updating function with recording the screen as an animation GIF image.
 //
 // This encodes each screen at each frame and may slows the application.

ebitenutil/loadimage.go

@@ -24,11 +24,12 @@ import (
 	"github.com/hajimehoshi/ebiten"
 )
 
-// NewImageFromFile loads the file path and returns ebiten.Image and image.Image.
+// NewImageFromFile loads the file with path and returns ebiten.Image and image.Image.
 //
-// The current directory for path depends on your environment. This will vary on your desktop or web browser.
+// How to solve path depends on your environment. This varies on your desktop or web browser.
 // Note that this doesn't work on mobiles.
-// It'll be safer to embed your resource, e.g., with github.com/jteeuwen/go-bindata instead of using this function.
+//
+// Instead of using this function, it is safer to embed your resources, e.g., with github.com/jteeuwen/go-bindata .
 func NewImageFromFile(path string, filter ebiten.Filter) (*ebiten.Image, image.Image, error) {
 	file, err := OpenFile(path)
 	if err != nil {

mobile/mobile.go

@@ -12,6 +12,9 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+// Package mobile provides functions for mobile platforms (Android and iOS).
+//
+// For usage, see https://github.com/hajimehoshi/ebiten/wiki/Mobile, https://github.com/hajimehoshi/ebiten/wiki/Android and https://github.com/hajimehoshi/ebiten/wiki/iOS.
 package mobile
 
 import (
@@ -31,7 +34,6 @@ func Start(f func(*ebiten.Image) error, width, height int, scale float64, title
 }
 
 // Update updates and renders the game.
-//
 // This should be called on every frame.
 //
 // On Android, this should be called at onDrawFrame of Renderer (used by GLSurfaceView).
@@ -45,13 +47,24 @@ func Update() error {
 //
 // This should be called with onTouchEvent of GLSurfaceView like this:
 //
+//     private double mDeviceScale = 0.0;
+//
+//     // pxToDp converts an value in pixels to dp.
+//     private double pxToDp(double x) {
+//         if (mDeviceScale == 0.0) {
+//             mDeviceScale = getResources().getDisplayMetrics().density;
+//         }
+//         return x / mDeviceScale;
+//     }
+//
 //     @Override
 //     public boolean onTouchEvent(MotionEvent e) {
 //         for (int i = 0; i < e.getPointerCount(); i++) {
 //             int id = e.getPointerId(i);
 //             int x = (int)e.getX(i);
 //             int y = (int)e.getY(i);
-//             YourGame.UpdateTouchesOnAndroid(e.getActionMasked(), id, x, y);
+//             // Exported function for UpdateTouchesOnAndroid
+//             YourGame.UpdateTouchesOnAndroid(e.getActionMasked(), id, (int)pxToDp(x), (int)pxToDp(y));
 //         }
 //         return true;
 //     }
@@ -93,7 +106,7 @@ func UpdateTouchesOnAndroid(action int, id int, x, y int) {
 //         [self updateTouches:touches];
 //     }
 //
-// The coodinate x/y is in points.
+// The coodinate x/y is in point.
 //
 // For more details, see https://github.com/hajimehoshi/ebiten/wiki/iOS.
 func UpdateTouchesOnIOS(phase int, ptr int64, x, y int) {

text/text.go

@@ -256,11 +256,12 @@ var textM sync.Mutex
 // Draw draws a given text on a given destination image dst.
 //
 // face is the font for text rendering.
-// (x, y) represents a 'dot' position. Be careful that this doesn't represent left-upper corner position.
+// (x, y) represents a 'dot' (period) position.
+// Be careful that this doesn't represent left-upper corner position.
 // clr is the color for text rendering.
 //
 // Glyphs used for rendering are cached in least-recently-used way.
-// It is OK to call this function with a same text and a same face at every frame.
+// It is OK to call this function with a same text and a same face at every frame in terms of performance.
 //
 // This function is concurrent-safe.
 func Draw(dst *ebiten.Image, text string, face font.Face, x, y int, clr color.Color) {