diff options
| -rw-r--r-- | documentation/src/development.dox | 119 | ||||
| -rw-r--r-- | documentation/src/migration_1_3.dox | 4 |
2 files changed, 37 insertions, 86 deletions
diff --git a/documentation/src/development.dox b/documentation/src/development.dox index 11fe2c467..b64d776e8 100644 --- a/documentation/src/development.dox +++ b/documentation/src/development.dox @@ -4,24 +4,15 @@ This chapter describes FLTK development and documentation. -\note documentation with doxygen will be described here. - <H2>Example</H2> -\note - -In the following code example(s) "*" will be replaced by "#" -as a temporary solution. - -\code - - -/## \file - Fl_Clock, Fl_Clock_Output widgets . #/ +\verbatim +/** \file + Fl_Clock, Fl_Clock_Output widgets. */ -/## +/** \class Fl_Clock_Output \brief This widget can be used to display a program-supplied time. @@ -32,56 +23,54 @@ as a temporary solution. \image latex clock.png "" width=10cm \image html round_clock.png \image latex clock.png "" width=10cm - \image html round_clock.png "" width=10cm #/ + \image html round_clock.png "" width=10cm */ - /## + /** Returns the displayed time. Returns the time in seconds since the UNIX epoch (January 1, 1970). \see value(ulong) - #/ + */ ulong value() const {return value_;} -/## +/** Set the displayed time. Set the time in seconds since the UNIX epoch (January 1, 1970). \param[in] v seconds since epoch \see value() - #/ + */ void Fl_Clock_Output::value(ulong v) { [...] } -/## +/** Create an Fl_Clock widget using the given position, size, and label string. The default boxtype is \c FL_NO_BOX. \param[in] X, Y, W, H position and size of the widget \param[in] L widget label, default is no label - #/ -Fl_Clock::Fl_Clock(int X, int Y, int W, int H, const char #L) + */ +Fl_Clock::Fl_Clock(int X, int Y, int W, int H, const char *L) : Fl_Clock_Output(X, Y, W, H, L) {} -/## +/** Create an Fl_Clock widget using the given boxtype, position, size, and label string. \param[in] t boxtype \param[in] X, Y, W, H position and size of the widget \param[in] L widget label, default is no label - #/ -Fl_Clock::Fl_Clock(uchar t, int X, int Y, int W, int H, const char #L) + */ +Fl_Clock::Fl_Clock(uchar t, int X, int Y, int W, int H, const char *L) : Fl_Clock_Output(X, Y, W, H, L) { type(t); box(t==FL_ROUND_CLOCK ? FL_NO_BOX : FL_UP_BOX); } - - -\endcode +\endverbatim \note From Duncan: (will be removed later, just for now as a reminder) -5. I've just added comments for the fl_color_chooser() functions, and + I've just added comments for the fl_color_chooser() functions, and in order to keep them and the general Function Reference information for them together, I created a new doxygen group, and used \\ingroup in the three comment blocks. This creates a new Modules page (which @@ -97,37 +86,40 @@ From Duncan: (will be removed later, just for now as a reminder) as the first doxygen command in the function's comment puts it in the appropriate place. There is no need to have \\defgroup and \\ingroup as well, and indeed they don't work. So, to summarize: -\code + +\verbatim Gizmo.H - /## \class Gizmo + /** \class Gizmo A gizmo that does everything - #/ + */ class Gizmo { etc }; extern int popup_gizmo(...); Gizmo.cxx: - /## \relatesalso Gizmo + /** \relatesalso Gizmo Pops up a gizmo dialog with a Gizmo in it - #/ + */ int popup_gizmo(...); -\endcode +\endverbatim -<H3>Example comment:</H3> +<H3>Comments Within Doxygen Comment Blocks:</H3> You can use HTML comment statements to embed comments in doxygen comment blocks. These comments will not be visible in the generated document. +\code The following text is a developer comment. <!-- *** This *** is *** invisible *** --> This will be visible again. +\endcode + +will be shown as: -\code The following text is a developer comment. <!-- *** This *** is *** invisible *** --> This will be visible again. -\endcode <H3>Different Headlines:</H3> @@ -145,9 +137,7 @@ These comments will not be visible in the generated document. <H4>Headline in big text (H4)</H4> -\section development_non-ascii Non-ASCII characters - - if you came here from below: back to \ref development_links +\section development_non-ascii Non-ASCII Characters \code Doxygen understands many HTML quoting characters like @@ -159,50 +149,11 @@ This will appear in the document: Doxygen understands many HTML quoting characters like ", ü, ç, Ç, but not all HTML quoting characters. -For further informations about quoting see - \b http://www.stack.nl/~dimitri/doxygen/htmlcmds.html - -<H3>Example with UTF-8 encoded text</H3> - -\code - - <P>Assuming that the following source code was written on MS Windows, - this example will output the correct label on OS X and X11 as well. - Without the conversion call, the label on OS X would read - <tt>Fahrvergn¸gen</tt> with a deformed umlaut u ("cedille", - html "¸"). - \#code - btn = new Fl_Button(10, 10, 300, 25); - btn->copy_label(fl_latin1_to_local("Fahrvergnügen")); - \#endcode - - \note If your application uses characters that are not part of both - encodings, or it will be used in areas that commonly use different - code pages, you might consider upgrading to FLTK 2 which supports - UTF-8 encoding. - - \todo This is an example todo entry, please ignore ! - -\endcode - -This will appear in the document: - - <P>Assuming that the following source code was written on MS Windows, - this example will output the correct label on OS X and X11 as well. - Without the conversion call, the label on OS X would read - <tt>Fahrvergn¸gen</tt> with a deformed umlaut u ("cedille", - html "¸"). - \#code - btn = new Fl_Button(10, 10, 300, 25); - btn->copy_label(fl_latin1_to_local("Fahrvergnügen")); - \#endcode +For further informations about HTML quoting characters see + \b http://www.doxygen.org/htmlcmds.html - \note If your application uses characters that are not part of both - encodings, or it will be used in areas that commonly use different - code pages, you might consider upgrading to FLTK 2 which supports - UTF-8 encoding. +Alternatively you can use \b UTF-8 encoding within Doxygen comments. - \todo This is an example todo entry, please ignore ! \section development_structure Document Structure @@ -264,7 +215,7 @@ Links to other documents and external links can be embedded with unicode that has been created with a \page statement. - For further informations about quoting see - http://www.stack.nl/~dimitri/doxygen/htmlcmds.html + http://www.doxygen.org/htmlcmds.html - see <a href="http://www.nedit.org/">Nedit</a> creates a standard HTML link @@ -277,7 +228,7 @@ appears as: unicode that has been created with a \\page statement. - For further informations about quoting see - http://www.stack.nl/~dimitri/doxygen/htmlcmds.html + http://www.doxygen.org/htmlcmds.html - see <a href="http://www.nedit.org/">Nedit</a> creates a standard HTML link diff --git a/documentation/src/migration_1_3.dox b/documentation/src/migration_1_3.dox index 4c1f1bfba..6496c066a 100644 --- a/documentation/src/migration_1_3.dox +++ b/documentation/src/migration_1_3.dox @@ -40,8 +40,8 @@ Please refer to the \ref unicode chapter for more details. \note It is important that, although your software uses only ASCII characters for input to FLTK widgets, the user may enter non-ASCII characters, and FLTK -will return these characters with utf-8 encoding to your application, e.g. -via Fl_Input::value(). You \b will need to re-encode them to \b your (non-utf-8) +will return these characters with UTF-8 encoding to your application, e.g. +via Fl_Input::value(). You \b will need to re-encode them to \b your (non-UTF-8) encoding, otherwise you might see or print garbage in your data. |