standardese documentation generator version 0.3: Groups, inline documentation, template mode & more

After two bugfix release for the parsing code, I finally got around to implement more features for standardese. A complete refactoring of the internal code allowed me to implement some advanced features: standardese now comes with member groups, the ability to show inline documentation, a template language and many minor things that just improve the overall documentation generation.

» read more »
Author's profile picture Jonathan

Memory 0.6: Composition and Joint Allocators

If you’ve been a long reader of my blog, you might remember my memory library. I haven’t forgotten about it, even though the 0.5 release was in February! After three patches and a long pause in development to focus on standardese, I’ve finally finished the 0.6 release. It mainly provides two major features: composition and joint allocators.

» read more »
Author's profile picture Jonathan

Function templates - deduce template arguments or pass explicitly?

Function templates allow writing a single definition that can handle multiple different types. It is a very powerful form of C++’s static polymorphism.

When instantiating a class template, we have to pass in the types explictly (at least until C++17):

std::vector<int> vec;
std::basic_string<my_char, std::char_traits<my_char>> str;
std::tuple<int, bool, std::string> tuple;

But when instantiating a function template, the compiler can often figure the types out:

template <typename A, typename B, typename C>
void func(const A& a, const B& b, const C& c);

int x;
func(x, 'A', "hello");
// equivalent to:
func<int, char, const char*>(x, 'A', "hello");

Let’s look at this process into a little bit more detail and establish some guidelines as well as see how we can prohibit template argument deduction for arguments.

» read more »
Author's profile picture Jonathan

void foo(T& out) - How to fix output parameters

There are some cases where you need to return a value from a function but cannot use the return value. It happens, for example, in functions where you want to return multiple values at once. While you can pass multiple inputs to a function - the parameters, you cannot pass multiple return values in the same way.

C++ programmers tend to use a good old (lvalue) reference for that. You take a non-const reference as parameter and assign the output to that reference. The caller will pass a variable and upon function completion find the value of the variable changed.

Yet this approach has some problems: For starters, it is not obvious when just looking at the call that the variable is going to be changed. This is the reason that C++ style guides such as the one used by Google recommend using a pointer for that. The caller then has to explicitly pass in the address of the variable, making it explicit.

But with a pointer you can now pass in nullptr, you have to check for that in the function: A pointer where you really mean “reference” does not follow the guidelines I’ve been advocating for.

So is there not a universal solution?

There is, but first we need to understand the full scope of the problem.

» read more »
Author's profile picture Jonathan