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.
- Is my understanding correct ?
- 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.
- Is my understanding correct ?
- 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.
- Is my understanding correct ?
- 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.
- Is my understanding correct ?
- 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.