[PATCH xorg-gtest 14/16] xserver: update documentation

[Chase Douglas]

On 07/02/2012 11:44 PM, Peter Hutterer wrote:
> Signed-off-by: Peter Hutterer <peter.hutterer at who-t.net>
> ---
>   include/xorg/gtest/xorg-gtest-xserver.h |   21 ++++++++++++++++++++-
>   1 file changed, 20 insertions(+), 1 deletion(-)
>
> diff --git a/include/xorg/gtest/xorg-gtest-xserver.h b/include/xorg/gtest/xorg-gtest-xserver.h
> index 707888e..6eb2241 100644
> --- a/include/xorg/gtest/xorg-gtest-xserver.h
> +++ b/include/xorg/gtest/xorg-gtest-xserver.h
> @@ -40,7 +40,26 @@ namespace testing {
>   /**
>    * @class XServer xorg-gtest_xserver.h xorg/gtest/xorg-gtest_xserver.h
>    *
> - * Miscellaneous interfaces to communicate with the X server.
> + * Class representing the X server process.
> + *
> + * @code
> + * XServer server;
> + * server.SetOption("-logfile", "/tmp/Xserver.log");
> + *
> + * try {
> + *   server.Start();
> + * } catch (const std::runtime_error &e) {
> + *   std::cerr << "Problem starting the X server: " << e.what() << std::endl;
> + * }

Generally, code shouldn't be using try...catch blocks unless it really 
expects a specific problem. If the X server won't start, then just let 
the test crash out (gtest will catch it and print the message for you).

The reason I mention this is that I don't think we generally want to 
lead people to adding try...catch blocks everwhere in their code, which 
is the wrong way to do proper exception handling. When done properly, 
exception handling is a lot easier, and usually don't have to use any 
try...catch blocks.

TBH, I've only recently learned how to do exception handling properly, 
so there's a chance you'll come across some of my own code that does it 
wrong too :).

All of that said, we probably should add an "@throws" doxygen comment to 
state that it throws a std::runtime_error if the process fails to start.

> + * ...
> + *
> + * if (!server.Terminate()) {
> + *   std::cerr << "Problem terminating server ... killing now ..." << std::endl;
> + *   if (!server.Kill())
> + *     std::cerr << "Problem killing server" << std::endl;
> + * }
> + * @endcode
>    */
>   class XServer : public xorg::testing::Process {
>     public:
>