Add @remarks to supplement DESCRIPTION

[roydukkey]

As a preference, I believe it is best practice to hace concise descriptions. However, there are often times when more details on a function or mixin benefit documenting complex behaviour.

I would suggest a @remarks annotation be provide for these cases. This concept exists in Microsoft's XMLDocs and might serve as a reference to this feature and usage.

///
/// Removes all values from a `$list` at `$index` onward an `$amount` of positions.
///
/// @param {List} $list - List containing the value to be removed.
/// @param {Number} $index - Index indicating the first value to be removed.
/// @param {Number} $amount - Number indicating the amount of positions to be removed
///      from the `$index`.
///
/// @return {List} - Returns a new list without the specified `$index`.
///
/// @remarks This function accepts negatives values for `$index` and `$amount` and will
///      traverse backward when negatives are provide. For example, [etc. ...]
///

[steffenpedersen]

This is a great idea. We will definitely use that in further development.