Naming convention and documentation

[malashin]

Hello,

It's seems that *Texture.GL_BindTexture() and *Texture.GL_UnbindTexture() should be renamed to *Texture.GL_Bind() and *Texture.GL_Unbind().
https://github.com/veandco/go-sdl2/blob/master/sdl/render.go#L573-L589

Is it ok to do? I'm asking since it's quite a breaking change, but there was a similar commit before 4dfff38.

---

The other thing I'd like to do is to add proper documentation for goDoc.
I've found that someone tried to do this here https://github.com/veandco/go-sdl2/blob/master/sdl/pixels.go#L212-L216.

Should we really have function name stated on two lines and have the link in perentesis?

// UpdateYUV updates a rectangle within a planar YV12 or IYUV texture with new pixel data.
// UpdateYUV (https://wiki.libsdl.org/SDL_UpdateYUVTexture)
func (texture *Texture) UpdateYUV(rect *Rect, yPlane []byte, yPitch int, uPlane []byte, uPitch int, vPlane []byte, vPitch int) error {}

Maybe one of this versions is a better option?

// UpdateYUV updates a rectangle within a planar YV12 or IYUV texture with new pixel data.
// https://wiki.libsdl.org/SDL_UpdateYUVTexture
func (texture *Texture) UpdateYUV(rect *Rect, yPlane []byte, yPitch int, uPlane []byte, uPitch int, vPlane []byte, vPitch int) error {}

// UpdateYUV updates a rectangle within a planar YV12 or IYUV texture with new pixel data. (https://wiki.libsdl.org/SDL_UpdateYUVTexture)
func (texture *Texture) UpdateYUV(rect *Rect, yPlane []byte, yPitch int, uPlane []byte, uPitch int, vPlane []byte, vPitch int) error {}

[veeableful]

Hi @malashin, that's a good point. The GL_BindTexture and GL_UnbindTexture should just be GL_Bind and GL_Unbind. I can tag current master as v0.2 so we can introduce breaking changes for the next cycle. Do you want to PR for this?

As for the UpdateYUV, perhaps we can just remove the description altogether since this is just a binding and people can go to the link. But I'm fine with keeping it as it is.

[malashin]

@veeableful, renamed the functions:
#266

---

I was not talking about UpdateYUV specifically, it was just an example. I'm up for adding proper documentation for all the functions, but I need some sort of approved formatting for it.

Currently the documentation is all over the place. Some functions have it, some don't. Not sure why methods have objects names in docs instead of the methods names.

This comment here is the closest to proper Go formatting, but method name is stated twice:
https://github.com/veandco/go-sdl2/blob/master/sdl/pixels.go#L212-L216

This one has objects name:
https://github.com/veandco/go-sdl2/blob/master/sdl/pixels.go#L290-L294

Even @houndci is reporting this:

comment on exported method Texture.GLUnbind should be of the form "GLUnbind ..."

GoDoc guidlines:

The convention is simple: to document a type, variable, constant, function, or even a package, write a regular comment directly preceding its declaration, with no intervening blank line. Godoc will then present that comment as text alongside the item it documents. For example, this is the documentation for the fmt package's Fprint function:

// Fprint formats using the default formats for its operands and writes to w.
// Spaces are added between operands when neither is a string.
// It returns the number of bytes written and any write error encountered.
func Fprint(w io.Writer, a ...interface{}) (n int, err error) {

Notice this comment is a complete sentence that begins with the name of the element it describes. This important convention allows us to generate documentation in a variety of formats, from plain text to HTML to UNIX man pages, and makes it read better when tools truncate it for brevity, such as when they extract the first line or sentence.

https://blog.golang.org/godoc-documenting-go-code

[veeableful]

You're right. I guess we were just stuck in between choosing whether to make it easier for C people or Go people and ended up somewhere in the middle which is probably not good.

What do you think if we follow the godoc guidelines and append the link at the end for the documentation? That's a lot of functions to go through though. I wish we have a way to automate these to just take from the official SDL2 wiki using a script during pre-compile time.

Side note: I've tagged the master as v0.2 before merging your PR.

[malashin]

What do you think if we follow the godoc guidelines and append the link at the end for the documentation?

Yes, this is the one I'm in favor of.

// UpdateYUV updates a rectangle within a planar YV12 or IYUV texture with new pixel data.
// (https://wiki.libsdl.org/SDL_UpdateYUVTexture)
func (texture *Texture) UpdateYUV(rect *Rect, yPlane []byte, yPitch int, uPlane []byte, uPitch int, vPlane []byte, vPitch int) error {}

There are several problems with the automation. All the docs must be there on github for goDoc to function. This means that the script can not be run on compile, but before a commit instead. The wording of description on SDL wiki is not 100% compatible:

Use this function to update a rectangle within a planar YV12 or IYUV texture with new pixel data.

Should be UpdateYUV updates a rectangle within a planar YV12 or IYUV texture with new pixel data.. It can obviously be worked around in this way UpdateYUV - Use this function to update a rectangle within a planar YV12 or IYUV texture with new pixel data.. But I'd rather rewrite them.

Here is an example that it was actually done right before, just not for every function:
https://godoc.org/github.com/veandco/go-sdl2/sdl#Rect

[veeableful]

The SDL2 wiki function description seems quite structured. I'll look into the automation part. Seems pretty doable to make it look the same as how you would write the Go function description 😁

[malashin]

I've added documentation for render.go pretty much by hand. Do you need it PRed or should we wait for the automation?
malashin@c0f3914

The patterns I was able to determine from this are:
"Use this function to get" -> "returns"
Everything else like "Use this function to set", "...copy", "...destroy" has to be transformed into third person singulars, like "sets", "copies", etc.

The other possible problem is if description has direct mention of another SDL function. I replaced it with the function name from our bindings.
https://wiki.libsdl.org/SDL_SetTextureBlendMode

Use this function to set the blend mode for a texture, used by SDL_RenderCopy().
SetBlendMode sets the blend mode for a texture, used by Renderer.Copy().

[veeableful]

Yeah definitely. We'll merge the PR first. Thank you very much for doing this. I know there's a lot of function descriptions there need rewriting.

I plan to start with writing a program for getting all the function descriptions and then we can break down the structure and generalize it well enough so the transformation works on all functions. I will add the program under tools directory when it's ready to be worked on together.