Author: Peter Keung
Date: 2007-01-25 00:14:36 +0100 (Thu, 25 Jan 2007)
New Revision: 4566
Log:
Edited Debug eZ Component tutorial
Modified:
trunk/Debug/docs/tutorial.txt
Modified: trunk/Debug/docs/tutorial.txt
===================================================================
--- trunk/Debug/docs/tutorial.txt 2007-01-24 22:33:02 UTC (rev 4565)
+++ trunk/Debug/docs/tutorial.txt 2007-01-24 23:14:36 UTC (rev 4566)
@@ -1,4 +1,4 @@
-eZ components - Debug
+eZ Components - Debug
~~~~~~~~~~~~~~~~~~~~~
.. contents:: Table of Contents
@@ -7,18 +7,18 @@
============
The Debug component provides an API to log and time debug events. This
-component depends mainly on the EventLog. The functionality of the Debug
-component is devided in two parts:
+component depends mainly on the EventLog component. The functionality of the
+Debug component is divided into two parts:
- Writing debug messages.
- Measuring the execution time.
Writing a debug message is almost the same as writing a message with the
-EventLog. However, there is one major distinction. Messages written with the
-EventLog are supposed to be written to a storage (log files, database, etc).
-Messages written with the Debug component are usually directly formatted and
-displayed. Note that the Debug::log() method has a slightly different signature
-than the EventLog::log() method.
+EventLog component. However, there is one major distinction: messages written
+with the EventLog component are intended to be written to a storage element
+(such as a log file or database). Messages written with the Debug component are
+usually directly formatted and displayed. Note that the Debug::log() method has
+a slightly different signature than the EventLog::log() method.
Timing information is captured by starting and stopping timers using the public
methods from ezcDebug. The timing information is stored in a structure with raw
@@ -26,49 +26,49 @@
script.
The Debug summary output can be formatted with an implementation from
-ezcDebugOutputFormatter. The default, and currently only, implementation of a
-formatter is ezcDebugHtmlFormatter. This HTML formatter transforms the raw log
-messages and raw timing information in a HTML string. This HTML string can be
-displayed at the end of each HTML page (generated by a PHP script).
+ezcDebugOutputFormatter. The default, and currently only, formatter is
+ezcDebugHtmlFormatter. This HTML formatter transforms the raw log
+messages and raw timing information into a HTML string for display.
Class overview
==============
-The following classes are most important to use, extend, or implement:
+The following classes are the most important to use, extend or implement:
ezcDebug
- Provides the public API for writing Debug messages and capturing timing
+ This provides the public API for writing Debug messages and capturing timing
information.
ezcDebugOutputFormatter
- The ezcDebugOutputFormatter provides an interface for the debug output
+ ezcDebugOutputFormatter provides an interface for the debug output
format. New implementations can format the raw log messages and timing
- information in any output format.
+ information to any output format.
ezcDebugHtmlFormatter
- ezcDebugHtmlFormatter is an implementation from the ezcDebugOutputFormatter
+ ezcDebugHtmlFormatter is an implementation of the ezcDebugOutputFormatter
interface. This formatter reads the raw log and timing information and
- returns it as a string with a HTML layout. This string can be output directly
- in the HTML page.
+ returns it as an HTML string. This string can be output directly
+ to an HTML page.
-See class documentation for more information.
+See the API documentation for more information.
Usage
=====
-Writing a log message to a file.
---------------------------------
+Writing a log message to file
+-----------------------------
The following script writes a message to the Debug component. At the end of the
-script the log message is formatted and printed.
+script, the log message is formatted and printed.
.. include:: tutorial_log_message.php
:literal:
-Writing log messages is almost the same as writing them to the EventLog. As a
-matter of fact, the EventLog is internally used.
+Writing log messages is almost the same as writing them to the EventLog
+component. As a matter of fact, the EventLog component is internally used by
+Debug.
Further information about writing log messages can be found in the EventLog
component.
@@ -79,42 +79,42 @@
The timers from ezcDebug can be used for two purposes:
-- Timers, measure the time between two points in the program.
-- Accumulators, get the current time after a certain point (for example after
- starting the script)
+- Timers measure the time between two points in the program.
+- Accumulators get the current time after a certain point (for example after
+ starting the script).
-Both methods are executed with ezcDebug::startTimer(), ezcDebug::stopTimer(),
+Both methods are executed with ezcDebug::startTimer(), ezcDebug::stopTimer()
and ezcDebug::switchTimer(). The next script demonstrates the usage of these
methods:
.. include:: tutorial_timers.php
:literal:
-The output looks like:
+The output is as follows:
.. image:: img/debug_tutorial_timers.png
-The output has two groups: output and accumulators. In the group "output" are
-two timers: "Hello world" and "Goodbye cruel world".
+The output has two groups: output and accumulators. There are two timers in the
+"output" group: "Hello world" and "Goodbye cruel world".
-The "accumulators" group has one timer, which is called "Program runtime". This
-timer took in total: 0.00034 seconds. In this timer are several "switch
+The "accumulators" group has one timer called "Program runtime". This
+timer took a total of 0.00034 seconds. In this timer are several "switch
timers". These show the time since the "Program runtime" was started.
Recursive timers
----------------
-Sometimes a specific code block repeats. For example to measure the time a
-PHP statement takes in a loop. The Debug timer will calculate the avarage time
-of the repeative statement and display it in the debug summary. See the next
-script:
+You can also time repeating code blocks. For example, you can measure the time
a
+PHP statement takes in a loop. The Debug timer will calculate the average time
+of the repeating statement and display it in the debug summary. See the next
+example:
.. include:: tutorial_recursive_timers.php
:literal:
-And the output is as follows:
+The resulting output is as follows:
.. image:: img/debug_tutorial_recursive_timers.png
--
svn-components mailing list
svn-components@lists.ez.no
http://lists.ez.no/mailman/listinfo/svn-components
