docs: Use 'Deprecated:' annotation

Fixes #1160

audio/audio.go

@@ -208,7 +208,9 @@ func (c *Context) IsReady() bool {
 	return r
 }
 
-// Update is deprecated as of 1.6.0-alpha.
+// Update does nothing.
+//
+// Deprecated: (as of 1.6.0) Do not use this.
 //
 // As of 1.6.0-alpha, Update always returns nil and does nothing related to updating the state.
 // You don't have to call Update any longer.

audio/mp3/decode_gopherjs.go

@@ -98,7 +98,9 @@ func (s *Stream) Length() int64 {
 	return int64(len(s.leftData) * 4)
 }
 
-// Size is deprecated as of 1.6.0-alpha. Use Length instead.
+// Size returns the size of decoded stream in bytes.
+//
+// Deprecated: (as of 1.6.0) Use Length instead.
 func (s *Stream) Size() int64 {
 	return s.Length()
 }

audio/mp3/decode_notgopherjs.go

@@ -67,7 +67,9 @@ func (s *Stream) Length() int64 {
 	return s.orig.Length()
 }
 
-// Size is deprecated as of 1.6.0-alpha. Use Length instead.
+// Size returns the size of decoded stream in bytes.
+//
+// Deprecated: (as of 1.6.0) Use Length instead.
 func (s *Stream) Size() int64 {
 	return s.Length()
 }

audio/vorbis/vorbis.go

@@ -56,7 +56,9 @@ func (s *Stream) Length() int64 {
 	return s.size
 }
 
-// Size is deprecated as of version 1.6.0-alpha. Use Length instead.
+// Size returns the size of decoded stream in bytes.
+//
+// Deprecated: (as of 1.6.0) Use Length instead.
 func (s *Stream) Size() int64 {
 	return s.Length()
 }

audio/wav/decode.go

@@ -54,7 +54,9 @@ func (s *Stream) Length() int64 {
 	return s.size
 }
 
-// Size is deprecated as of version 1.6.0-alpha. Use Length instead.
+// Size returns the size of decoded stream in bytes.
+//
+// Deprecated: (as of 1.6.0) Use Length instead.
 func (s *Stream) Size() int64 {
 	return s.Length()
 }

colorm.go

@@ -67,7 +67,10 @@ func (c *ColorM) Concat(other ColorM) {
 	c.impl = c.impl.Concat(other.impl)
 }
 
-// Add is deprecated as of 1.5.0-alpha.
+// Add adds a matrix, but in a wrong way.
+//
+// Deprecated: (as of 1.5.0) Do not use this.
+//
 // Note that this doesn't make sense as an operation for affine matrices.
 func (c *ColorM) Add(other ColorM) {
 	c.impl = c.impl.Add(other.impl)
@@ -113,28 +116,36 @@ func (c *ColorM) SetElement(i, j int, element float64) {
 	c.impl = c.impl.SetElement(i, j, float32(element))
 }
 
-// Monochrome is deprecated as of 1.6.0-alpha. Use ChangeHSV(0, 0, 1) instead.
+// Monochrome returns a color matrix for monochrome.
+//
+// Deprecated: (as of 1.6.0) Use ChangeHSV(0, 0, 1) instead.
 func Monochrome() ColorM {
 	c := ColorM{}
 	c.ChangeHSV(0, 0, 1)
 	return c
 }
 
-// ScaleColor is deprecated as of 1.2.0-alpha. Use Scale instead.
+// ScaleColor returns a color matrix for scaling.
+//
+// Deprecated: (as of 1.2.0) Use Scale instead.
 func ScaleColor(r, g, b, a float64) ColorM {
 	c := ColorM{}
 	c.Scale(r, g, b, a)
 	return c
 }
 
-// TranslateColor is deprecated as of 1.2.0-alpha. Use Translate instead.
+// TranslateColor returns a color matrix for translating.
+//
+// Deprecated: (as of 1.2.0) Use Translate instead.
 func TranslateColor(r, g, b, a float64) ColorM {
 	c := ColorM{}
 	c.Translate(r, g, b, a)
 	return c
 }
 
-// RotateHue is deprecated as of 1.2.0-alpha. Use RotateHue member function instead.
+// RotateHue returns a color matrix for chanting the hue.
+//
+// Deprecated: (as of 1.2.0-alpha) Use RotateHue member function instead.
 func RotateHue(theta float64) ColorM {
 	c := ColorM{}
 	c.RotateHue(theta)

ebitenutil/gif.go

@@ -105,10 +105,10 @@ 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.
 //
+// Deprecated: (as of 1.6.0) Do not use this.
+//
 // This encodes each screen at each frame and may slows the application.
 //
 // Here is the example to record initial 120 frames of your game:

geom.go

@@ -98,7 +98,10 @@ func (g *GeoM) Concat(other GeoM) {
 	g.ty = ty
 }
 
-// Add is deprecated as of 1.5.0-alpha.
+// Add adds a matrix, but in a wrong way.
+//
+// Deprecated: (as of 1.5.0) Do not use this.
+//
 // Note that this doesn't make sense as an operation for affine matrices.
 func (g *GeoM) Add(other GeoM) {
 	g.a_1 += other.a_1
@@ -230,21 +233,27 @@ func (g *GeoM) SetElement(i, j int, element float64) {
 	}
 }
 
-// ScaleGeo is deprecated as of 1.2.0-alpha. Use Scale instead.
+// ScaleGeo returns a geometry matrix for scaling.
+//
+// Deprecated: (as of 1.2.0) Use Scale instead.
 func ScaleGeo(x, y float64) GeoM {
 	g := GeoM{}
 	g.Scale(x, y)
 	return g
 }
 
-// TranslateGeo is deprecated as of 1.2.0-alpha. Use Translate instead.
+// TranslateGeo returns a geometry matrix for translating.
+//
+// Deprecated: (as of 1.2.0) Use Translate instead.
 func TranslateGeo(tx, ty float64) GeoM {
 	g := GeoM{}
 	g.Translate(tx, ty)
 	return g
 }
 
-// RotateGeo is deprecated as of 1.2.0-alpha. Use Rotate instead.
+// RotateGeo returns a geometry matrix for rotating.
+//
+// Deprecated: (as of 1.2.0) Use Rotate instead.
 func RotateGeo(theta float64) GeoM {
 	g := GeoM{}
 	g.Rotate(theta)

image.go

@@ -505,13 +505,13 @@ type DrawImageOptions struct {
 	// Otherwise, Filter specified at DrawImageOptions is used.
 	Filter Filter
 
-	// Deprecated (as of 1.5.0-alpha): Use SubImage instead.
+	// Deprecated: (as of 1.5.0) Use SubImage instead.
 	ImageParts ImageParts
 
-	// Deprecated (as of 1.1.0-alpha): Use SubImage instead.
+	// Deprecated: (as of 1.1.0) Use SubImage instead.
 	Parts []ImagePart
 
-	// Deprecated (as of 1.9.0-alpha): Use SubImage instead.
+	// Deprecated: (as of 1.9.0) Use SubImage instead.
 	SourceRect *image.Rectangle
 }
 
@@ -571,7 +571,9 @@ func newScreenFramebufferImage(width, height int) *Image {
 	return i
 }
 
-// MaxImageSize is deprecated as of 1.7.0-alpha. No replacement so far.
+// MaxImageSize represented the maximum size of an image, but now this constant is deprecated.
+//
+// Deprecated: (as of 1.7.0) No replacement so far.
 //
 // TODO: Make this replacement (#541)
 var MaxImageSize = 4096

imageparts.go

@@ -18,13 +18,17 @@ import (
 	"image"
 )
 
-// An ImagePart is deprecated (as of 1.1.0-alpha): Use SubImage instead.
+// ImagePart is sub image regions of the source and destination images.
+//
+// Deprecated: (as of 1.1.0) Use SubImage instead.
 type ImagePart struct {
 	Dst image.Rectangle
 	Src image.Rectangle
 }
 
-// An ImageParts is deprecated (as of 1.5.0-alpha): Use SubImage instead.
+// ImageParts is sub image regions of the source and destination images.
+//
+// Deprecated: (as of 1.5.0) Use SubImage instead.
 type ImageParts interface {
 	Len() int
 	Dst(i int) (x0, y0, x1, y1 int)

input.go

@@ -203,7 +203,9 @@ func TouchPosition(id int) (int, int) {
 	return uiDriver().Input().TouchPosition(id)
 }
 
-// Touch is deprecated as of 1.7.0. Use TouchPosition instead.
+// Touch represents a touch.
+//
+// Deprecated: (as of 1.7.0). Use TouchPosition instead.
 type Touch interface {
 	// ID returns an identifier for one stroke.
 	ID() int
@@ -226,7 +228,9 @@ func (t *touch) Position() (x, y int) {
 	return t.x, t.y
 }
 
-// Touches is deprecated as of 1.7.0. Use TouchIDs instead.
+// Touches returns the current touches.
+//
+// Deprecated: (as of 1.7.0) Use TouchIDs instead.
 func Touches() []Touch {
 	var ts []Touch
 	for _, id := range TouchIDs() {

mobile/compat.go

@@ -35,10 +35,10 @@ func (g *game) Layout(viewWidth, viewHeight int) (screenWidth, screenHeight int)
 	return g.width, g.height
 }
 
-// Start is deprecated as of 1.10.0-alpha. Use `ebitenmobile` command and `SetGame` instead.
-//
 // Start starts the game and returns immediately.
 //
+// Deprecated: (as of 1.10.0) Use `ebitenmobile` command and `SetGame` instead.
+//
 // Different from ebiten.Run, this invokes only the game loop and not the main (UI) loop.
 //
 // The unit of width/height is device-independent pixel (dp on Android and point on iOS).
@@ -61,11 +61,11 @@ func Start(f func(*ebiten.Image) error, width, height int, scale float64, title
 	return nil
 }
 
-// Update is deprecated as of 1.10.0-alpha. Use `ebitenmobile` command and `SetGame` instead.
-//
 // Update updates and renders the game.
 // This should be called on every frame.
 //
+// Deprecated: (as of 1.10.0) Use `ebitenmobile` command and `SetGame` instead.
+//
 // If Update is called before Start is called, Update panics.
 //
 // On Android, this should be called at onDrawFrame of Renderer (used by GLSurfaceView).
@@ -79,10 +79,10 @@ func Update() error {
 	return ebitenmobileview.Update()
 }
 
-// UpdateTouchesOnAndroid is deprecated as of 1.10.0-alpha. Use `ebitenmobile` command instead.
-//
 // UpdateTouchesOnAndroid updates the touch state on Android.
 //
+// Deprecated: (as of 1.10.0) Use `ebitenmobile` command instead.
+//
 // This should be called with onTouchEvent of GLSurfaceView like this:
 //
 //     private double mDeviceScale = 0.0;
@@ -118,10 +118,10 @@ func UpdateTouchesOnAndroid(action int, id int, x, y int) {
 	ebitenmobileview.UpdateTouchesOnAndroid(action, id, x, y)
 }
 
-// UpdateTouchesOnIOS is deprecated as of 1.10.0-alpha. Use `ebitenmobile` command instead.
-//
 // UpdateTouchesOnIOS updates the touch state on iOS.
 //
+// Deprecated: (as of 1.10.0) Use `ebitenmobile` command instead.
+//
 // This should be called with touch handlers of UIViewController like this:
 //
 //     - (GLKView*)glkView {

run.go

@@ -72,7 +72,9 @@ type Game interface {
 // TPS represents a default ticks per second, that represents how many times game updating happens in a second.
 const DefaultTPS = 60
 
-// FPS is deprecated as of 1.8.0-alpha: Use DefaultTPS instead.
+// FPS represents the default TPS (tick per second). This is for backward compatibility.
+//
+// Deprecated: (as of 1.8.0) Use DefaultTPS instead.
 const FPS = DefaultTPS
 
 // CurrentFPS returns the current number of FPS (frames per second), that represents
@@ -129,7 +131,9 @@ func IsDrawingSkipped() bool {
 	return atomic.LoadInt32(&isDrawingSkipped) != 0
 }
 
-// IsRunningSlowly is deprecated as of 1.8.0-alpha. Use Game's Draw function instead.
+// IsRunningSlowly is an old name for IsDrawingSkipped.
+//
+// Deprecated: (as of 1.8.0) Use Game's Draw function instead.
 func IsRunningSlowly() bool {
 	return IsDrawingSkipped()
 }
@@ -338,12 +342,16 @@ func ScreenSizeInFullscreen() (int, int) {
 	return uiDriver().ScreenSizeInFullscreen()
 }
 
-// MonitorSize is deprecated as of 1.8.0-alpha. Use ScreenSizeInFullscreen instead.
+// MonitorSize is an old name for ScreenSizeInFullscreen
+//
+// Deprecated: (as of 1.8.0) Use ScreenSizeInFullscreen instead.
 func MonitorSize() (int, int) {
 	return ScreenSizeInFullscreen()
 }
 
-// SetScreenSize is deprecated as of 1.11.0-alpha. Use SetWindowSize and RunGame (Game's Layout) instead.
+// SetScreenSize sets the game screen size and resizes the window.
+//
+// Deprecated: (as of 1.11.0) Use SetWindowSize and RunGame (Game's Layout) instead.
 func SetScreenSize(width, height int) {
 	if width <= 0 || height <= 0 {
 		panic("ebiten: width and height must be positive")
@@ -351,7 +359,9 @@ func SetScreenSize(width, height int) {
 	theUIContext.setScreenSize(width, height)
 }
 
-// SetScreenScale is deprecated as of 1.11.0-alpha. Use SetWindowSize instead.
+// SetScreenScale sets the game screen scale and resizes the window.
+//
+// Deprecated: (as of 1.11.0-alpha). Use SetWindowSize instead.
 func SetScreenScale(scale float64) {
 	if scale <= 0 {
 		panic("ebiten: scale must be positive")
@@ -359,7 +369,9 @@ func SetScreenScale(scale float64) {
 	theUIContext.setScaleForWindow(scale)
 }
 
-// ScreenScale is deprecated as of 1.11.0-alpha. Use WindowSize instead.
+// ScreenScale returns the game screen scale.
+//
+// Deprecated: (as of 1.11.0-alpha) Use WindowSize instead.
 func ScreenScale() float64 {
 	return theUIContext.getScaleForWindow()
 }
@@ -389,12 +401,16 @@ func SetCursorMode(mode CursorModeType) {
 	uiDriver().SetCursorMode(driver.CursorMode(mode))
 }
 
-// IsCursorVisible is deprecated as of 1.11.0-alpha. Use CursorMode instead.
+// IsCursorVisible reports whether the cursor is visible or not.
+//
+// Deprecated: (as of 1.11.0-alpha) Use CursorMode instead.
 func IsCursorVisible() bool {
 	return CursorMode() == CursorModeVisible
 }
 
-// SetCursorVisible is deprecated as of 1.11.0-alpha. Use SetCursorMode instead.
+// SetCursorVisible sets the cursor visibility.
+//
+// Deprecated: (as of 1.11.0-alpha) Use SetCursorMode instead.
 func SetCursorVisible(visible bool) {
 	if visible {
 		SetCursorMode(CursorModeVisible)
@@ -403,7 +419,9 @@ func SetCursorVisible(visible bool) {
 	}
 }
 
-// SetCursorVisibility is deprecated as of 1.6.0-alpha. Use SetCursorMode instead.
+// SetCursorVisibility sets the cursor visibility.
+//
+// Deprecated: (as of 1.6.0-alpha) Use SetCursorMode instead.
 func SetCursorVisibility(visible bool) {
 	SetCursorVisible(visible)
 }
@@ -458,7 +476,9 @@ func IsRunnableOnUnfocused() bool {
 	return uiDriver().IsRunnableOnUnfocused()
 }
 
-// IsRunnableInBackground is deprecated as of 1.11.0-alpha. Use IsRunnableOnUnfocused instead.
+// IsRunnableInBackground is an old name for IsRunnableOnUnfocused.
+//
+// Deprecated: (as of 1.11.0) Use IsRunnableOnUnfocused instead.
 func IsRunnableInBackground() bool {
 	return IsRunnableOnUnfocused()
 }
@@ -478,7 +498,9 @@ func SetRunnableOnUnfocused(runnableOnUnfocused bool) {
 	uiDriver().SetRunnableOnUnfocused(runnableOnUnfocused)
 }
 
-// SetRunnableInBackground is deprecated as of 1.11.0-alpha. Use SetRunnableOnUnfocused instead.
+// SetRunnableInBackground is an old name for SetRunnableOnUnfocused.
+//
+// Deprecated: (as of 1.11.0-alpha) Use SetRunnableOnUnfocused instead.
 func SetRunnableInBackground(runnableInBackground bool) {
 	SetRunnableOnUnfocused(runnableInBackground)
 }