Question

I’ve got a compile-time recursive type that looks somewhat like this:

template <typename DataType, typename LeftNode, typename RightNode>
struct fixed_tree{
    fixed_tree(const DataType& data, const LeftNode& left, const RightNode& right) :     data_(data),left_(left),right_(right){}
    DataType data_;
    LeftNode left_;
    RightNode right_;
};

That class has some specializations for various leaf nodes where Left/Right Node is void, but that’s not important.

This recursive class is then passed as an argument to a function creating a somewhat lengthy typename.

namespace some_namespace{
void some_function(int some_param0, int some_param1, fixed_tree<std::string,
                                                        fixed_tree<int, 
                                                            fixed_tree<float, void, void >,
                                                            fixed_tree<double, void, void > 
                                                            >,
                                                        fixed_tree<int,
                                                            fixed_tree<double,void,
                                                                fixed_tree<char, 
                                                                    fixed_tree<int, void,void>,
                                                                    fixed_tree<int, void,void>
                                                                > >,
                                                            void 
                                                            >   
                                                        > somewhat_lengthy_type
                );

When I run this through Doxygen the function documentation overflows the line quite badly.

My question is: Is there a way to hint/force line breaks outside the doxygen comment blocks, so that the look in the documentation resembles what’s in the source.

I’m not very interested in the following solutions:

Using a typedef. Even though the example doesn’t share this trait, the actual type forms a self-explanatory syntax that actually helps to make sense what the interface does.

Custom CSS. Would be nice to avoid messing around with something that’s not doxygen tags.

Answer 1

IMO that’s definitely something you should typedef out. Including the entire type when so long is poor practice. Doing so would solve the doxygen issue, as well as making a much simpler type (I can see typos coming from the current one quite easily). If that tree is deep, you should also pass by reference.

In doxygen, you can use more specific tags like:

/**
 * @method name Docs.
 */

to document a particular bit of code. These usually add on to the autogenerated docs, however, and I’m not sure if you can entirely overwrite those.

Quite simply, the fact it looks ugly in your code/docs should be a huge tipoff that it is ugly and should be refactored.