Improve and clarify documentation

1 files changed, 16 insertions, 11 deletions

diff --git a/src/Fl_Device.cxx b/src/Fl_Device.cxx
index 86b5e8cdd..c723186f2 100644
--- a/src/Fl_Device.cxx
+++ b/src/Fl_Device.cxx
@@ -72,17 +72,22 @@
 */
 
 /** Make this surface the current drawing surface.
- This surface will receive all future graphics requests.
- \p Starting from FLTK 1.4.0, the preferred API to change the current drawing surface
- is Fl_Surface_Device::push_current( ) / Fl_Surface_Device::pop_current().
- \note It's recommended to use this function only as follows :
- \li The current drawing surface is the display;
- \li make current another surface, e.g., an Fl_Printer or an Fl_Image_Surface object,  calling set_current() on this object;
- \li draw to that surface;
- \li make the display current again with Fl_Display_Device::display_device()->set_current();  . Don't do any other call to set_current() before this one.
-
- Other scenarios of drawing surface changes should be performed via Fl_Surface_Device::push_current( ) / Fl_Surface_Device::pop_current().
- */
+  This surface will receive all future graphics requests.
+
+  Since FLTK 1.4.0 the preferred API to change the current drawing surface
+  is Fl_Surface_Device::push_current( ) / Fl_Surface_Device::pop_current().
+
+  \note It is recommended to use this function only as follows :
+    - The current drawing surface is the display;
+    - make current another surface, e.g., an Fl_Printer or an Fl_Image_Surface object,
+      calling set_current() on this object;
+    - draw to that surface;
+    - make the display current again with Fl_Display_Device::display_device()->set_current();\n
+      don't do any other call to set_current() before this one.
+
+  Other scenarios of drawing surface changes should be performed via
+  Fl_Surface_Device::push_current() and Fl_Surface_Device::pop_current().
+*/
 void Fl_Surface_Device::set_current(void)
 {
   if (surface_) surface_->end_current();