From a1ac574a602f64440ff973bb2eea0e944b099a76 Mon Sep 17 00:00:00 2001 From: Hajime Hoshi Date: Tue, 19 May 2020 01:50:53 +0900 Subject: [PATCH] docs: Use 'Deprecated:' annotation Fixes #1160 --- audio/audio.go | 4 ++- audio/mp3/decode_gopherjs.go | 4 ++- audio/mp3/decode_notgopherjs.go | 4 ++- audio/vorbis/vorbis.go | 4 ++- audio/wav/decode.go | 4 ++- colorm.go | 21 ++++++++++++---- ebitenutil/gif.go | 4 +-- geom.go | 17 ++++++++++--- image.go | 10 +++++--- imageparts.go | 8 ++++-- input.go | 8 ++++-- mobile/compat.go | 16 ++++++------ run.go | 44 ++++++++++++++++++++++++--------- 13 files changed, 105 insertions(+), 43 deletions(-) diff --git a/audio/audio.go b/audio/audio.go index 8a5a56eca..0cc744687 100644 --- a/audio/audio.go +++ b/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. diff --git a/audio/mp3/decode_gopherjs.go b/audio/mp3/decode_gopherjs.go index 8a20e48f2..6b1012342 100644 --- a/audio/mp3/decode_gopherjs.go +++ b/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() } diff --git a/audio/mp3/decode_notgopherjs.go b/audio/mp3/decode_notgopherjs.go index 8abcc0e20..9a9982605 100644 --- a/audio/mp3/decode_notgopherjs.go +++ b/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() } diff --git a/audio/vorbis/vorbis.go b/audio/vorbis/vorbis.go index a5342a21e..852947877 100644 --- a/audio/vorbis/vorbis.go +++ b/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() } diff --git a/audio/wav/decode.go b/audio/wav/decode.go index e6323ae70..0953cab2d 100644 --- a/audio/wav/decode.go +++ b/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() } diff --git a/colorm.go b/colorm.go index 07cbeeb3f..96543a752 100644 --- a/colorm.go +++ b/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) diff --git a/ebitenutil/gif.go b/ebitenutil/gif.go index 8126b929f..4a29f9047 100644 --- a/ebitenutil/gif.go +++ b/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: diff --git a/geom.go b/geom.go index be41a4600..84152261c 100644 --- a/geom.go +++ b/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) diff --git a/image.go b/image.go index 998735a99..4d85878af 100644 --- a/image.go +++ b/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 diff --git a/imageparts.go b/imageparts.go index ffa3118c4..80cc2a981 100644 --- a/imageparts.go +++ b/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) diff --git a/input.go b/input.go index 5974610c5..9e512b483 100644 --- a/input.go +++ b/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() { diff --git a/mobile/compat.go b/mobile/compat.go index 66a190dbf..bd96af550 100644 --- a/mobile/compat.go +++ b/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 { diff --git a/run.go b/run.go index b5f0a7241..4815f3e41 100644 --- a/run.go +++ b/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) }