From 0cfc13260167c54911e27c8a3abc917c243cef41 Mon Sep 17 00:00:00 2001 From: Albrecht Schlosser Date: Wed, 12 Jan 2011 09:20:11 +0000 Subject: Documentation updates. Reformatted development.dox, removed some old and obsolete parts. git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@8267 ea41ed52-d2ee-0310-a9c1-e6b18d33e121 --- documentation/src/development.dox | 119 +++++++++++--------------------------- 1 file changed, 35 insertions(+), 84 deletions(-) (limited to 'documentation/src/development.dox') 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. -

Example

-\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 -

Example comment:

+

Comments Within Doxygen Comment Blocks:

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 will be visible again. +\endcode + +will be shown as: -\code The following text is a developer comment. This will be visible again. -\endcode

Different Headlines:

@@ -145,9 +137,7 @@ These comments will not be visible in the generated document.

Headline in big text (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 - -

Example with UTF-8 encoded text

- -\code - -

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 - Fahrvergn¸gen 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: - -

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 - Fahrvergn¸gen 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 Nedit 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 Nedit creates a standard HTML link -- cgit v1.2.3