grouping documentation by source directory structure?

jessevdk / cldoc

clang based documentation generator for C and C++

GNU General Public License v2.0

553 stars 59 forks source link

grouping documentation by source directory structure? #99

Open rhl- opened 9 years ago

rhl- commented 9 years ago

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

jessevdk commented 9 years ago

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 commented 9 years ago

Closing since no further arguments have been provided.

cbiffle commented 9 years ago

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 commented 9 years ago

Definitely want to have easy lookup to which header to include for a certain symbol. This is currently missing.
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.