grouping documentation by source directory structure?

[rhl-]

Is it possible to group source code in the documentation by the header files directory structure?

[jessevdk]

This is not possible. Directory structure is not a particular good way of grouping documentation since the structure can be arbitrary. It can make it harder to find documentation of specific symbols. Namespaces and classes are the natural grouping. See also https://github.com/jessevdk/cldoc/issues/11#issuecomment-14071281.

I'm not going to consider this until I hear a really compelling argument for it.

[jessevdk]

Closing since no further arguments have been provided.

[cbiffle]

FWIW, this was the first thing I tried with cldoc, and I'm a bit boggled at its absence.

It seems to be very difficult, when viewing (say) a function in the cldoc HTML output, to determine which header I need to include to get access to it.

Since in C/C++, like it or not, headers and directory structure are a thing we have to deal with, it would also seem reasonable to view a list of headers contributing to the documentation, and to be able to describe what each header is for.

User's use case:

• Find a type they're interested in.
• Learn that it is defined in stuff.h.
• Become curious what else they are bringing in by #include "stuff.h"
• View header description and list of contents.

[jessevdk]

1. Definitely want to have easy lookup to which header to include for a certain symbol. This is currently missing.
2. Having access to a list of symbols per header seems useful and reasonable.

I still think the main view should be the way it is, but I would like to add the possibility for exposing these two types of information.