Structuring Examples

[craffael]

As @anianruoss already noted in #52 (comment) there are some problems with the structure and goal of the example's. At the moment we have a whole bunch of small sample applications that serve multiple purposes:

1. Some of them (integration) test the LehrFEM++ library. They have been used by a developer to see if the newly implemented code works as expected, see e.g. (mesh/structured_mesh_demo.cc, base/ref_el_output.cc, static_vars_demo.cc).
2. Some of them focus on a single class/function and show how to use it. E.g. mesh/structured_mesh_demo.cc, geometry/geometry_output.cc, base/ref_el_output.cc
3. Some of them illustrate how to combine multiple classes to achieve something, e.g. refinement/refinement_demo.cc, io/io_demo.cc.

I would argue, that examples serving only purpose 1. should not be part of the LehrFEM++ repository because they do not add value (anymore). E.g. the example base/ref_el_output.cc doesn't really help prospective users to understand LehrFEM++ and it is not executed on a regular basis to see if the expected output appears on the command line.

Examples serving only purpose 2. would be ideal candidates for doxygen snippets, they should be moved there.

Examples serving only purpose 3. could be used as a basis for a doxygen page (see manual below) that explains in more depth how a goal can be achieved. However, a lot more work must be invested to achieve this. It doesn't suffice to just convert commented source code into a doxygen page.

I see the following problems with the current situation:

• The examples are not referenced from the doxygen documentation.
• At the moment examples do not serve a single purpose. So, if someone wants to learn about building structured meshes (mesh/structured_mesh_demo.cc), he will also encounter various mesh testing routines.
• It is hard to maintain all these examples so that they follow best practices. E.g. It would be better if mesh/structured_mesh_demo.cc would use the boost::program_options library.

Future

I think the only value that examples can possible contribute to the LehrFEM++ repository is that they help prospective users to get started with the code. However, in most cases examples are not the best means to document the code. In fact, I think there are two other much more important ways of documenting code and I think this is very we should focus most of our attention to:

Documentation of classes/functions with inline doxygen comments

This type of documentation is built from the doxygen comments in the code. It is the most important type of documentation as it documents every behavior of a class/method. The goal should be, that users of a class/method don't have to read the source code but that they understand how to use a class/function by looking at the documentation. I think it's a good thing if this type of documentation is rather extensive, it can/should include doxygen snippets (see e.g. here) that explain how to use the class!

The big advantage of this type of documentation is that it is rather easy to keep the comments updated: Whenever we change something in the code we must remember to also change the comments just above the code. Moreover, if we modify one class/function we (usually) don't have to modify the documentation of other classes/functions.

The disadvantage is of course that it is rather hard to document concepts that span multiple classes which is why we need another type of documentation.

Manual

This type of documentation is built from specialized Doxygen pages (folder doc/doxygen/pages). The goal is that these pages connect the dots and show how the many classes in LehrFEM++ can be combined to achieve a goal. Most of the details can be skipped here, it's important to get the overall picture right. It's however important to reference the class/function level documentation that provides more details.

The big problem with this type of documentation is, that it becomes outdated eventually. Therefore, I suggest to use it only for the most important concepts.

The role of examples

I think examples make mostly sense as an "attachement" to a page of the manual. I.e. if the manual explains how to solve a Poisson equation on the unit square, then there could be an example that contains the actual code. At the end of the manual page we could then add a reference to this example.

The problem with examples as a primary sort of documentation is that they are rather inefficient: If I want to learn how to write a VtkFile through examples, I need to scan through 100 lines of code (examples/io/io_demo.cc) so I can find the three important lines that I was missing. Moreover, many concepts and ideas that are part of the VtkWriter probably do not become clear just by reading the code. On the other hand, I think the snippet that is contained in doxygen contains much more information about the VtkWriter.
In general, I think it's much better to create a snippet and include it in the documentation of the corresponding class.

Of course, there will be many occasions where we want to write a piece of code that uses LehrFEM++, e.g.

• for exercises (lecture),
• research
• perform real calculations
• benchmarking
• etc.
  But in all these cases it makes more sense to create a separate repository and include LehrFEM++ as a hunter package (not yet done) because this code doesn't contribute to LehrFEM++ at all, it simply uses LehrFEM++ as a library. For the time being, this sort of code can go into the examples folder, but soon I would push it into a separate repository.

[craffael]

@hiptmair @anianruoss What do you think?

[hiptmair]

Admittedly, the examples are in a messy state. However, we should not embark on a big cleansing campaign at this stage of LehrFEM++ development. I think, first many so-called examples of LehrFEM++ functionality should be included and what is not appropriate can be moved to another location later. In particular the finite element part of the code is still under development and not stable.

In my experience, examples are essential for C++ FE code development, because one usually relies on a skeleton example when implementing new functionality. I agree, that snippets are also very usefu; to that end and, eventually, we should make heavy use of them.

[craffael]

Yes, as a skeleton examples are very useful. But we should strive to have not too many of those examples because, most of them will probably look very similarly.
I also agree that we can move the examples out of the repository at a later point in time. But I suggest that we don't spend too much time documenting the examples. It's much more important that the classes/functions are well documented.

[anianruoss]

I agree with many of the points already made. From a student's perspective (mine), it is best to keep the number of example codes to a minimum, covering only the most important basic functionalities. Otherwise, it is very easy to lose the overview of what is relevant and what is not. Keeping these examples in a single place, such as the Manual, is a very good idea. However, I would also add snippets to these pages and not only to the documentation of the respective classes. In my opinion, it is easier to grasp a concept if one sees a couple of lines of code accompanying a description.