On 01/24/12 06:46, Albrecht Schlosser wrote: > On 23.01.2012 22:54, Greg Ercolano wrote: >> One of the things I liked about the old 1.1.x docs >> was we were able to make comments against the docs. >> Kinda handy for users. > > ... to ask support questions and make suggestions for changes > where they don't belong ;-)
Ha, yes, good for users, but bad for devs who expect STR's for all suggs. Thing is, doc comments fill a gap; users are more likely to make a comment than report an STR: o People who wanna complain about something want to be heard. Adding a comment in the docs is sure to be seen, and can be a freeform complaint, whereas an STR is mostly just seen by devs and not other users. (Often doc comments are more 'emotional' because their frustration level is fresh ;) o I think many doc bugs or usage problems go unreported as STRs because folks often don't feel motivated to switch gears while they're programming to fill out a bug report. Sometimes comments might raise false alarms, but devs or other users can reply showing the "fix". o Sometimes users want to point out something that is perhaps not a bug or a doc mod request, but a gotchya they ran into that they would never report as an STR. o Folks can help each other in the comments forum, which can be handy. o Devs can notice issues in these comments forums that might show a trend of usage issues that may indicate designs should change. When folks run into issues, its easy to say 'hey, I had to do this to make things work' or 'there's a bug in the docs where it says xxx'. I'm almost sure we miss 90% of such feedback because folks won't make the extra effort to report these things as a bug report. They're just trying to move on through their day. I know I for one will report problems I run into with the microsoft API through their documentation feedback forum. But I never bother to report it through their bug system. Doc comments are kinda nice, cause it's contextual. For instance, being a dev on Fl_Table, it's easy for me to keep an eye on Fl_Table related comments, b/c I often refer to the docs on the website. >> Not sure how to pull this off with doxygen, but perhaps >> we can make a post-process for our doxygen website pages >> that hooks some HTML at the bottom of all the doxygen pages >> that allows users to comment. Perhaps we can make our own hidden html comments in the doxygen docs. This is something our website docs post process could search and replace with our appropriate "comments" html code. So for instance, at the bottom of a widget's source code, we could have: <!-- FLTK_COMMENTS_MARKER: Fl_Widget --> ..that would get inserted into the doxygen html docs. This would be ignored by web browsers if built locally on a user's machine, but our website post process would insert a blob of html that adds a comment section for the Fl_Widget. This way, no matter what doxygen's hashing method is used for filenames, we just search and replace all of their html looking for that special marker. IIRC there's a way to insert raw HTML code into doxygen docs which should make it through doxygen's html generator unmolested, so our post process can detect it. Should be a simple bit of perl. Perhaps one issue though is with spam. I don't think comments are moderated, so not sure how we can keep spammers out, other than capatchas or logins or some such. _______________________________________________ fltk-dev mailing list fltk-dev@easysw.com http://lists.easysw.com/mailman/listinfo/fltk-dev