Godoc comments including link to original library call about go-sdl2

[aqiank]

Hi, sorry for the late reply!

Definitely, we really could use a better documentation than we have right now (or lack thereof). If you're interested in developing a script that programatically adds the documentation, we are more than happy to accept it.

[Stantheman]

Sorry for the late reply back :) I've been finishing up Hacker School and didn't have time to try this until today.

I have a branch with very basic documentation applied to exported functions where my script could apply them. It looks for function names and types and tries to find documentation in the SDL wiki for that thing. The output is just the name, then the link to documentation in parenthesis. Here's an example:

// GetNumAudioDrivers (https://wiki.libsdl.org/SDL_GetNumAudioDrivers)

The script added 443 lines like this. It doesn't handle sdl_* types -- the ttf, mixer, and image libraries. The documentation for these libs are structured in an annoying way (the URLs end in numbers, which would need to be preprocessed: http://www.libsdl.org/projects/docs/SDL_image/SDL_image_15.html).

The changes can be viewed at https://github.com/Stantheman/go-sdl2/compare/docgen?expand=1.

Since this is a big change, and I'm not sure how you feel about this documentation style (being so simple), I did not PR it. I think it's a good launching point/better than nothing, but didn't want to submit the PR if you'd rather do it more organically. I've looked through it a few times and the links all seem to be correct, but a second set of eyes would also be useful. If you're interested I'll submit the PR.

[Stantheman]

Additionally, the following 79 methods were not converted, excluding the sdl_* entries. Many of them appear to be macros or helper functions. Ideally these would be documented as well:

>>> AudioCallback in sdl/audio.go doesnt map to a known URL
>>> AudioFilter in sdl/audio.go doesnt map to a known URL
>>> AudioDeviceID in sdl/audio.go doesnt map to a known URL
>>> AudioDeviceConnected in sdl/audio.go doesnt map to a known URL
>>> HasAVX in sdl/cpuinfo.go doesnt map to a known URL
>>> ErrorCode in sdl/error.go doesnt map to a known URL
>>> Error in sdl/error.go doesnt map to a known URL
>>> OutOfMemory in sdl/error.go doesnt map to a known URL
>>> Unsupported in sdl/error.go doesnt map to a known URL
>>> CEvent in sdl/events.go doesnt map to a known URL
>>> CommonEvent in sdl/events.go doesnt map to a known URL
>>> KeyDownEvent in sdl/events.go doesnt map to a known URL
>>> KeyUpEvent in sdl/events.go doesnt map to a known URL
>>> JoyDeviceEvent in sdl/events.go doesnt map to a known URL
>>> ControllerAxisEvent in sdl/events.go doesnt map to a known URL
>>> ControllerButtonEvent in sdl/events.go doesnt map to a known URL
>>> ControllerDeviceEvent in sdl/events.go doesnt map to a known URL
>>> RenderEvent in sdl/events.go doesnt map to a known URL
>>> OSEvent in sdl/events.go doesnt map to a known URL
>>> ClipboardEvent in sdl/events.go doesnt map to a known URL
>>> EventAction in sdl/events.go doesnt map to a known URL
>>> EventFilter in sdl/events.go doesnt map to a known URL
>>> EventWatchHandle in sdl/events.go doesnt map to a known URL
>>> SetEventFilterFunc in sdl/events.go doesnt map to a known URL
>>> FilterEventsFunc in sdl/events.go doesnt map to a known URL
>>> AddEventWatchFunc in sdl/events.go doesnt map to a known URL
>>> GetEventState in sdl/events.go doesnt map to a known URL
>>> GameControllerBindType in sdl/gamecontroller.go doesnt map to a known URL
>>> GameControllerAxis in sdl/gamecontroller.go doesnt map to a known URL
>>> GameControllerButton in sdl/gamecontroller.go doesnt map to a known URL
>>> GameController in sdl/gamecontroller.go doesnt map to a known URL
>>> GameControllerButtonBind in sdl/gamecontroller.go doesnt map to a known URL
>>> func (GameControllerButtonBind) Type in sdl/gamecontroller.go doesnt map to a known URL
>>> func (GameControllerButtonBind) Button in sdl/gamecontroller.go doesnt map to a known URL
>>> func (GameControllerButtonBind) Axis in sdl/gamecontroller.go doesnt map to a known URL
>>> func (GameControllerButtonBind) Hat in sdl/gamecontroller.go doesnt map to a known URL
>>> func (GameControllerButtonBind) HatMask in sdl/gamecontroller.go doesnt map to a known URL
>>> GestureID in sdl/gesture.go doesnt map to a known URL
>>> Haptic in sdl/haptic.go doesnt map to a known URL
>>> Btoi in sdl/helpers.go doesnt map to a known URL
>>> Joystick in sdl/joystick.go doesnt map to a known URL
>>> JoystickGUID in sdl/joystick.go doesnt map to a known URL
>>> JoystickID in sdl/joystick.go doesnt map to a known URL
>>> Update in sdl/joystick.go doesnt map to a known URL
>>> LogOutputFunction in sdl/log.go doesnt map to a known URL
>>> Cursor in sdl/mouse.go doesnt map to a known URL
>>> SystemCursor in sdl/mouse.go doesnt map to a known URL
>>> Button in sdl/mouse.go doesnt map to a known URL
>>> ButtonLMask in sdl/mouse.go doesnt map to a known URL
>>> ButtonMMask in sdl/mouse.go doesnt map to a known URL
>>> ButtonRMask in sdl/mouse.go doesnt map to a known URL
>>> ButtonX1Mask in sdl/mouse.go doesnt map to a known URL
>>> ButtonX2Mask in sdl/mouse.go doesnt map to a known URL
>>> func (PixelFormat) Free in sdl/pixels.go doesnt map to a known URL
>>> func (Rect) IntersectLine in sdl/rect.go doesnt map to a known URL
>>> RendererInfoData in sdl/render.go doesnt map to a known URL
>>> func (RWops) ReadU8 in sdl/rwops.go doesnt map to a known URL
>>> func (RWops) WriteU8 in sdl/rwops.go doesnt map to a known URL
>>> func (Surface) PixelNum in sdl/surface.go doesnt map to a known URL
>>> func (Surface) BytesPerPixel in sdl/surface.go doesnt map to a known URL
>>> func (Surface) Pixels in sdl/surface.go doesnt map to a known URL
>>> func (Surface) Data in sdl/surface.go doesnt map to a known URL
>>> Renderer in sdl/sysrender.go doesnt map to a known URL
>>> WindowsInfo in sdl/syswm.go doesnt map to a known URL
>>> X11Info in sdl/syswm.go doesnt map to a known URL
>>> DFBInfo in sdl/syswm.go doesnt map to a known URL
>>> CocoaInfo in sdl/syswm.go doesnt map to a known URL
>>> UIKitInfo in sdl/syswm.go doesnt map to a known URL
>>> func (SysWMInfo) GetWindowsInfo in sdl/syswm.go doesnt map to a known URL
>>> func (SysWMInfo) GetX11Info in sdl/syswm.go doesnt map to a known URL
>>> func (SysWMInfo) GetDFBInfo in sdl/syswm.go doesnt map to a known URL
>>> func (SysWMInfo) GetCocoaInfo in sdl/syswm.go doesnt map to a known URL
>>> func (SysWMInfo) GetUIKitInfo in sdl/syswm.go doesnt map to a known URL
>>> TouchID in sdl/touch.go doesnt map to a known URL
>>> FingerID in sdl/touch.go doesnt map to a known URL
>>> Finger in sdl/touch.go doesnt map to a known URL
>>> Window in sdl/video.go doesnt map to a known URL
>>> GLContext in sdl/video.go doesnt map to a known URL
>>> SW_YUVTexture in sdl/yuv_sw_c.go doesnt map to a known URL

[Stantheman]

I decided to open the PR in case you do want to merge it to save us a round trip.