Improve documentation of DataOutFaces

[nfehn]

I wanted to use DataOutFaces recently and want to share some obstacles that I have noticed in this context. The code

  DataOutFaces<dim, DoFHandler<dim>> data_out_surface(true /*surface only*/);
  data_out_surface.build_patches(mapping, n_subdivisions);

compiles, the constructor runs successfully, but gives a segmentation fault in build_patches(). I think the documentation could be improved regarding the following aspects:

• which combinations of attach_triangulation/attach_dof_handler/add_data_vector are necessary to get a code that runs without exception?
• the documentation of DataOutFaces refers to the one of DataOut, which is not a base class? For example, one can use DataOutBase::VtkFlags for high-order output in DataOut, but does this automatically translate to DataOutFaces?
• would it make sense that the release version of the code detects that something is missing in order to proceed in build_patches() and asserts with some useful information?

[drwells]

Did it segmentation fault in debug mode? If so, could you attach your sample code so we can figure out why there was no assertion failure?

[nfehn]

No, in debug mode it says
"For the operation you are attempting, you first need to tell the DataOut or related object which DoFHandler or triangulation you would like to work on."

[bangerth]

Well, did you call DataOutFaces::attach_dof_handler()? As @drwells already said, a little testcase would be useful :-)

[nfehn]

That's my point. I can imagine that it is pretty clear for a deal.II developer that one must call attach_dof_handler(). I expected the documentation to make me aware of the prerequisities of build_patches(). The code that does the job in my case is

  DataOutFaces<dim, DoFHandler<dim>> data_out_surface(true /*surface only*/);
  data_out_surface.attach_triangulation(triangulation);
  data_out_surface.build_patches(mapping, n_subdivisions);

I only want to write the surface mesh in order to visualize the contours of the geometry. What I also found out is that attach_dof_handler() renders attach_triangulation() superfluous, is that correct? These things should be in the documentation. The question whether to assert also in release mode is a question of philosophy. I would do that.

[bangerth]

Yes, attach_dof_handler() implies attach_triangulation(). And I agree that all of these things should be documented better -- it's one of our oldest classes, its documentation largely predates the time when we became good at documenting. Patches are always welcome :-)

As for the need to call attach_*() before build_patches() -- that could be checked by an assertion. Regular Assert() is good enough -- you should only switch to release mode if your program runs correctly in debug mode, and in the current case that means that you've put the attach_*() call somewhere. We don't need to re-check that in release mode.