Request for pre-tag support in descriptions.

[docbill]

I am trying to format the follow JavaDoc comments in a manner suitable for ApexDox

/**
 * @description
 * This Class implements some useful limit utilities.  One example on how to use this
 * call is you write your trigger methods to look something like:
 * 
 * <pre>
 *    public void salesAccountUpdate() {
 *        try {
 *           if(newList.size() > 1) {
 *               LimitHelper.push(SALES_ACCOUNT_UPDATE_SETTING);
 *           }
 *           ...
 *        }
 *        catch(LimitHelper.LimitsException ex) {
 *           ...
 *        }
 *        finally {
 *            if(newList.size() > 1) {
 *                LimitHelper.pop(SALES_ACCOUNT_UPDATE_SETTING);
 *            }
 *        }
 *    }
 * </pre>
 * 
 * The catch exception or an after trigger is where you can add code to use deferred
 * processing to handle one record at the time so you do not hit the limits.
 * 
 * The LimitHelper name you are pushing and poping is the master label of the Limit Reserves
 * metadata type record that defines what how much time you reserving.
 * 
 * Then in order for this code to work there needs to be calls to the LimitHepler class to
 * check the limits periodically.  For example, immediately before a query you could call:
 * 
 * <pre>
 * (new LimitHelper()).setQueries(1).checkLimits( null);
 * </pre>
 * 
 * This is saying check the limits and make sure we have one query available beyound the
 * reserve.  If we do not either return an Exception or throw an exception.  The null
 * argument is the boolean that tells the helper if it should throw the exception.  If you
 * pass true, it will throw the exception.  If you pass false, it will return the exception.
 * Using a null value is equivalent to:
 * 
 * <pre>
 * (new LimitHelper()).setQueries(1).checkLimits( LimitHelper.throwsExceptionDefault );
 * </pre>
 * 
 * There are a series of DatabaseHelper.safe* methods that can be used to automatically
 * check the limits when performing DML operations.  e.g.
 * 
 * <pre>
 * for(DatabaseHelper.Result r : new DatabaseHelper().safeInsert(insertList)) {
 *     if(r.isSuccess()) {
 *         ...
 *     }
 * }
 * </pre>
 * 
 * By default we are checking a whole bunch of limits each time, but there are static
 * methods in the LimitHelper class for checking individual limits.
 */

This generates a single unreadable paragraph of:

This Class implements some useful limit utilities. One example on how to use this call is you write your trigger methods to look something like: <pre> public void salesAccountUpdate() { try { if(newList.size() > 1) { LimitHelper.push(SALES_ACCOUNT_UPDATE_SETTING); } ... } catch(LimitHelper.LimitsException ex) { ... } finally { if(newList.size() > 1) { LimitHelper.pop(SALES_ACCOUNT_UPDATE_SETTING); } } } </pre> The catch exception or an after trigger is where you can add code to use deferred processing to handle one record at the time so you do not hit the limits. The LimitHelper name you are pushing and poping is the master label of the Limit Reserves metadata type record that defines what how much time you reserving. Then in order for this code to work there needs to be calls to the LimitHepler class to check the limits periodically. For example, immediately before a query you could call: <pre> (new LimitHelper()).setQueries(1).checkLimits( null); </pre> This is saying check the limits and make sure we have one query available beyound the reserve. If we do not either return an Exception or throw an exception. The null argument is the boolean that tells the helper if it should throw the exception. If you pass true, it will throw the exception. If you pass false, it will return the exception. Using a null value is equivalent to: <pre> (new LimitHelper()).setQueries(1).checkLimits( LimitHelper.throwsExceptionDefault ); </pre> There are a series of DatabaseHelper.safe* methods that can be used to automatically check the limits when performing DML operations. e.g. <pre> for(DatabaseHelper.Result r : new DatabaseHelper().safeInsert(insertList)) { if(r.isSuccess()) { ... } } </pre> By default we are checking a whole bunch of limits each time, but there are static methods in the LimitHelper class for checking individual limits.

I tried breaking my text apart by adding an @example flag before each pre flag, and @description after each end pre flag. But all the examples are concat together, and all descriptions are concat together. I could probably give each example a reference number, and add in br between the description text, but that seems much less readable.

[no-stack-dub-sack]

@docbill This is an interesting suggestion and something I'm happy to consider. Finding the time to implement it is the greater challenge at the moment. Let me see if I can find some time soon to take this on. Also open to a PR if you feel like taking a stab at this yourself.