Add how-to add an algorithm guide and improve documentation of some internal classes

Add how-to add an algorithm guide and improve documentation of some internal classes #1894