/**
 * @file
 *
 *   Example file for Comment Reflower
 *
 * $Source $
 * $Id $
 * Copyright (C) 2004  Ian Nowland
 *
 * The purpose of Comment Reflower is to evenly wrap the wrappable text (as
 * opposed to all text) in comments. As you will notice this comment is not
 * evenly wrapped, much the same way as most comments in code begin to look
 * after a couple of edits. This hurts their readability, which in turn hurts
 * their maintainability. Comment Reflower attempts to fix this.
 *
 * The first thing to note about Comment Reflower is that it requires blank
 * lines to separate paragraphs. Thus because of the blank lines above the
 * previous paragraphs will not be reflowed into each other.
 *   The only time blank lines are not neccesary is when the new line is at a
 *   different indentation level to the previous. This is useful but having to 
 *   do so continually for plain English text would make it difficult to read.
 *
 * However, comment reflower has two more sophisticated features:-
 * - Bullet Points
 * - Break Reflow Strings
 * 
 * Bullet Points have two main implementation points:-
 * 1) Firstly when recognised on the next line they prevent the currently
 *    processed line from being flowed into them
 * 2) Secondly they can set the indentation level to be the right side of the
 *    bullet point, so that when text is reflowed it is done slightly indented,
 *    in the way Word processors do.
 *
 * Bullet points are just regular expressions matched against the start of the
 * line, and thus don't just have to be normal bullet points. For instance you
 * could do:
 * @doxygentag the comment for a doxygen tag, which will be wrapped at the right
 *             edge of the tag
 * @doxygentag2 the comment for a doxygen tag, which will be wrapped at the
 *              right edge of the tag             
 *
 * Break Reflow Strings are just regular expressions that if matched on a line
 * cause it never to be reflowed. So for instance:
 *
 * Underlines are matched not to reflow
 * ------------------------------------
 *
 * <xmlcomment>
 *   Xml comments on a line by themselves are never reflower, which is useful
 *   for c# style documentation
 * </xmlcomment>
 *
 * The HTML BR is recognised and respected, meaning a line with it at the end
 * like this.<BR>
 * Will never flow into the line immediately following it like this one.<BR>
 *
 * Also the xml pre block is recognised, so tables and things are never
 * reflowed:
 * <pre>
 * -----------------
 * |       |       |
 * -----------------
 * </pre>
 *
 * The other main features of Comment Reflower is that all blocks, bullets and
 * break flow strings are completely customisable, so you're not trapped with my
 * views as to what blocks should look like. It also leaves you free to add
 * support to any file types you may wish.
 *
 * Now to see on action on the othe blocks in the file you can either select
 * them and then go "Tools->Reflow Comment Containg Cursor", or you can select
 * the whole file and go "Tools->Reflow All Comments In Selected"
 */


/******************************************************************************
 * A C-style block comment, of the type some people use for functions and the
 * like. Comment Reflower ensures the start and end blocks never get put on the
 * same line.
 ******************************************************************************/

///////////////////////////////////////////////////////////////////////////////
// The same type of thing except for being C++ style.
///////////////////////////////////////////////////////////////////////////////

/* Now just a normal C-block comment. This behaves differently to the big
 * function type above in that the start of block is always on the same line as
 * actual comment. The end of line never is, unless the comment is 1 line, as
 * the next blocks demonstrate.
 */

/* Very short 1 line block with the ending on the same line */

/* Very short 1 line block which will reflow to be on 1 line. */

/* Too long 1 line block which will be reflowed to be over multiple lines, thus
 * respecting the wrap limit
 */


int j; /* Blocks are fine to be started ater code, so this will be reflowed
        * correctly.
        */
int /* However if code follows, the block will not be reflowed, no matter how long it is */ i;

/**
 * Doxygen comments are much like normal C comments, except the start of block
 * is on a line by itself if the comment is one line.
 */


/**
 * The bullet point rules are very useful to match to doxygen tags, to indent
 * the text that concerns them.
 *
 * @tag Very long text following tag1 that will be wrapped correctly
 * \tag this type of tag is happily recognised too and will be reflowed
 *      correctly.
 */

/*!
 * This type of doxygen block is recognised too, with the same behavious as the
 * last
 */

// C style comments are recognised too, and are faithfully reflowed to have the
// correct wrap.
       // As long as they hav different indentation,
int i; // or as long at they have text before them, then they will not be flowed
       // into each other

       // Blank lines work as well, of course.

///
/// <summary>
///   C# is a fan of doing comments like this, which I personally don't like as
///   it is a waste of whitespace.
/// </summary>
/// <param>
///   However because the break reflow strings recognise XML tags on a line by
///   themselves,
/// </param>
/// <param>
///   Then they are faithfully reflowed without screwing up the XML tag
///   formatting.
/// </param>

//
// Enough on block types for now, so looking at bullets points:
// 1) test - just a single line bullet
// 2) test - This line is far too long and so should wrap to the right hand side
//           of the word test
// 3) test - this bullet is wrapped too short and so should be wrapped up.
// Text at a normal indentation after a bullet. This should wrap normally.
// 1) A different type of bullet with the same type of start as the previous
//    one. Very long so that it has to wrap.
// 2) Just a short one that should be pulled up
//     - a hyphenated bullet pint. Again very long so that is has to wrap. Yes
//       this is vey long.
//     - bullet point by itself.
//     - bullet point to be wrapped
// @tag - Again very long so that is has to wrap. Yes this is very long. Yes
//        this is very long. In fact so long that it has to wrap down two lines.
//        In fact so long that it has to wrap down two lines.
// @tag Just checking that the other type of tag works correctly.
//      0 - now a single character followed by hyphen type bullet indented at
//          the same level as last
//      1 - a following bullet
//