C++ Edit Doc Comment with template arguments

[Johnco3]

I have the following method signature that I've been trying to document in a C++ header file.  Its got lots of template stuff in it so I understand that this might be quite challenging to document.  Here is the raw signature without any existing documentation comments.

Code: [Select]

template<typename InputIt1, typename InputIt2,
    typename OutputIt, typename Compare,
    typename Merge>
inline OutputIt custom_set_intersection(
    InputIt1 first1, InputIt1 last1,
    InputIt2 first2, InputIt2 last2,
    OutputIt d_first, Compare comp,
    Merge merge)

Documenting it via Ctrl+Shift+D makes this:

Code: [Select]

/**
 *
 * @param InputIt1
 * @param InputIt2
 * @param OutputIt
 * @param Compare
 * @param Merge
 * @param first1
 * @param last1
 * @param first2
 * @param last2
 * @param d_first
 * @param comp
 * @param merge
 *
 * @return
 */
template<typename InputIt1, typename InputIt2,
    typename OutputIt, typename Compare,
    typename Merge>
inline OutputIt custom_set_intersection(
    InputIt1 first1, InputIt1 last1,
    InputIt2 first2, InputIt2 last2,
    OutputIt d_first, Compare comp,
    Merge merge)

In actuality the real method parameters start at first1 and end with merge.  The first set of produced method parameters are template substitution types.   I'm not really sure how this would be documented via doxygen commenting, however - It may be useful to have something about the template types - but I think generally speaking this is not good practice as they are supposed to be substitution types.  The following page shows how it is supposed to be documented.
http://www.cplusplus.com/reference/algorithm/set_intersection/

Anyway, I removed the template substitution types, and filled in the details ending up with the following. (which is what I would like slickedit to have started with)

Code: [Select]

/**
 * this is adapted from the reference Microsoft implementation
 * of the set_intersection algorithm as the algorithm outlined
 * in http://en.cppreference.com/w/cpp/algorithm/set_intersection
 * may have bugs. customized set_intersection that merges
 * elements from both sets a pair with a default constructed
 * type of InputIt1.
 *
 * @param first1   [in] Input iterator to the initial position
 *                 of the first sorted sequence. The range used
 *                 is [first1,last1), which contains all the
 *                 elements between first1 and last1, including
 *                 the element pointed by first1 but not the
 *                 element pointed by last1
 * @param last1    [in] Input iterator to the final position of
 *                 the first sorted sequence. The range used is
 *                 [first1,last1), which contains all the
 *                 elements between first1 and last1, including
 *                 the element pointed by first1 but not the
 *                 element pointed by last1
 * @param first2   [in] Input iterators to the initial position
 *                 of the second sorted sequence. The range used
 *                 is [first2,last2).
 * @param last2    [in] Input iterators to the final position of
 *                 the second sorted sequence. The range used is
 *                 [first2,last2).
 * @param d_first  [in,out] Output iterator to the initial
 *                 position of the range where the resulting
 *                 sequence is stored. The pointed type shall
 *                 support being assigned the value of an
 *                 element from the first range.
 * @param comp     [in] Binary function that accepts two
 *                 arguments of the types pointed by the input
 *                 iterators, and returns a value convertible
 *                 to bool. The value returned indicates
 *                 whether the first argument is considered to
 *                 go before the second in the specific
 *                 strict weak ordering it defines. The function
 *                 shall not modify any of its arguments. This
 *                 can either be a function pointer or a
 *                 function object.
 * @param merge    [in] template argument to merge the input
 *                 sorted sequences into elements for the
 *                 OutputIt.
 *
 * @return An iterator to the end of the constructed range.
 */
template<typename InputIt1, typename InputIt2,
    typename OutputIt, typename Compare,
    typename Merge>
inline OutputIt custom_set_intersection(
    InputIt1 first1, InputIt1 last1,
    InputIt2 first2, InputIt2 last2,
    OutputIt d_first, Compare comp,
    Merge merge)
I think that the template args are useful, perhaps it could be some sort of user option to produce them or maintain them if the user has documented them.  I'm not sure.

[Dennis]

The correct JavaDoc syntax for type parameters is:

Code: [Select]

@param <T> the type of the elements in this collection
As illustrated in Java 1.7 LinkedList:

Code: [Select]


 * @see     ArrayList
 * @since 1.2
 * @param <E> the type of elements held in this collection
 */
public class LinkedList<E>
    extends AbstractSequentialList<E>
    implements List<E>, Deque<E>, Cloneable, java.io.Serializable
{

I am going to file a feature request to add support for this and add the option as you suggest in a future release.  It's not an easy fix so we can't work that into v19 at this point.