Minor documentation updates

Found a few cases of incorrect or misleading doxygen documentation while
looking through a few headers.

First, with the parachute removed, we no longer need
SDL_INIT_NOPARACHUTE or its documentation.
(SDL_remove_parachute_references.patch)

Secondly, the hint documentation for the X11 modesetting backends still
says that XRandR is disabled by default due to WM issues.
(SDL_update_x11_hint_docs.patch)

Finally ? and a bit more subjectively ? as SDL_SetWindowDisplayMode()
does not change the display mode of a window until next time it’s
changed from windowed?fullscreen
(http://bugzilla.libsdl.org/show_bug.cgi?id=1742), it’s probably worth
documenting that. There’s already a similar note for
SDL_SetWindowSize(), which would have to be removed if the patch in bug
#1742 is applied.
(SDL_add_doc_note_for_setwindowdisplaymode.patch)

Hope these help!

? David
-------------- next part --------------
A non-text attachment was scrubbed…
Name: SDL_add_doc_note_for_setwindowdisplaymode.patch
Type: text/x-patch
Size: 717 bytes
Desc: not available
URL: http://lists.libsdl.org/pipermail/sdl-libsdl.org/attachments/20130811/712e5c4d/attachment-0003.bin
-------------- next part --------------
A non-text attachment was scrubbed…
Name: SDL_remove_parachute_references.patch
Type: text/x-patch
Size: 1189 bytes
Desc: not available
URL: http://lists.libsdl.org/pipermail/sdl-libsdl.org/attachments/20130811/712e5c4d/attachment-0004.bin
-------------- next part --------------
A non-text attachment was scrubbed…
Name: SDL_update_x11_hint_docs.patch
Type: text/x-patch
Size: 1014 bytes
Desc: not available
URL: http://lists.libsdl.org/pipermail/sdl-libsdl.org/attachments/20130811/712e5c4d/attachment-0005.bin

Le dimanche, 11 ao?t 2013 ? 15:14, David Gow a ?crit :

Found a few cases of incorrect or misleading doxygen documentation while
looking through a few headers.

I have a question about maintenance of the documentation. It seems that what is on the wiki is/was generated from the headers. But I guess any correction made there doesn’t make it in the sources.

  1. Is my understanding correct ?
  2. If 1) is yes, doesn’t it feel wrong ?

Best,

Daniel

I think the initial documentation was made from the sources and after
that it’s all just user edits to the wiki. But yes, they’re separate.

2013/8/12, Daniel B?nzli <daniel.buenzli at erratique.ch>:> Le dimanche, 11 ao?t 2013 ? 15:14, David Gow a ?crit :

Found a few cases of incorrect or misleading doxygen documentation while
looking through a few headers.

I have a question about maintenance of the documentation. It seems that what
is on the wiki is/was generated from the headers. But I guess any correction
made there doesn’t make it in the sources.

  1. Is my understanding correct ?
  2. If 1) is yes, doesn’t it feel wrong ?

Best,

Daniel


SDL mailing list
SDL at lists.libsdl.org
http://lists.libsdl.org/listinfo.cgi/sdl-libsdl.org

I have a question about maintenance of the documentation. It seems that
what is on the wiki is/was generated from the headers. But I guess any
correction made there doesn’t make it in the sources.

  1. Is my understanding correct ?
  2. If 1) is yes, doesn’t it feel wrong ?

Yes, that’s correct, and Sam and I were just talking about this.

Here are the problems:

  • We’re usually better about updating docs in the headers than we are on
    the wiki (discounting the Wikipocalypse that happened over the last week).

  • You can write much more verbose documentation on the wiki, and do
    things like better formatting, say “just include this table from this
    other page” instead of cutting/pasting, etc. There’s some good
    discussion on some of the pages that I wouldn’t want to flood the
    headers with.

  • Anyone can update the wiki. The headers either need you to have push
    access, or send us patches, and both are demotivators (although, to be
    fair, I think we have to approve wiki write access at the moment).

  • The wiki doesn’t work offline (and pulling down wiki content into a
    big pile of HTML sucks in various ways).

As such, we don’t have a perfect solution at the moment, but we’re open
to changing anything. If something we like better comes along, I’ll
happily migrate the wiki contents into it.

This week, I believe the wiki is in much, much better shape than any
other documentation we offer, but that’s because Sam and I put full days
into improving it recently.

–ryan.

2013/8/12 Ryan C. Gordon

I have a question about maintenance of the documentation. It seems that

what is on the wiki is/was generated from the headers. But I guess any
correction made there doesn’t make it in the sources.

  1. Is my understanding correct ?
  2. If 1) is yes, doesn’t it feel wrong ?

Yes, that’s correct, and Sam and I were just talking about this.

Here are the problems:

  • We’re usually better about updating docs in the headers than we are on
    the wiki (discounting the Wikipocalypse that happened over the last week).

  • You can write much more verbose documentation on the wiki, and do things
    like better formatting, say "just include this table from this other page"
    instead of cutting/pasting, etc. There’s some good discussion on some of
    the pages that I wouldn’t want to flood the headers with.

  • Anyone can update the wiki. The headers either need you to have push
    access, or send us patches, and both are demotivators (although, to be
    fair, I think we have to approve wiki write access at the moment).

  • The wiki doesn’t work offline (and pulling down wiki content into a big
    pile of HTML sucks in various ways).

As such, we don’t have a perfect solution at the moment, but we’re open to
changing anything. If something we like better comes along, I’ll happily
migrate the wiki contents into it.

This week, I believe the wiki is in much, much better shape than any other
documentation we offer, but that’s because Sam and I put full days into
improving it recently.

–ryan.

I made the suggestion to Sam of having Wiki page comments like the PHP docs
have, as long as regenerating the Wiki pages from headers allows us to keep
those comments. I do agree that keeping two sets of documentations (headers
vs wiki) could be problematic, specially if they drift out of sync.–
Gabriel.