Doxygen suggestions

ROOT
1

Hello!

Here are some suggestions and requests to make the new-ish doxygen documentation better.

[list]
[*]Sorting Member functions: Please sort them alphabetically. Here are the relevant doxygen parameters.

[code]
SORT_MEMBER_DOCS

If the SORT_MEMBER_DOCS tag is set to YES (the default) then doxygen will sort the (detailed) documentation of file and class members alphabetically by member name. If set to NO the members will appear in declaration order.

SORT_BRIEF_DOCS

If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the brief descriptions of file, namespace and class members alphabetically by member name. If set to NO (the default) the members will appear in declaration order.

SORT_GROUP_NAMES

If the SORT_GROUP_NAMES tag is set to YES then doxygen will sort the hierarchy of group names into alphabetical order. If set to NO (the default) the group names will appear in their defined order.

SORT_BY_SCOPE_NAME
If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be sorted by fully-qualified names, including namespaces. If set to NO (the default), the class list will be sorted only by class name, not including the namespace part.

Note:
    This option is not very useful if HIDE_SCOPE_NAMES is set to YES. 
    This option applies only to the class list, not to the alphabetical list.

SORT_MEMBERS_CTORS_1ST
If the SORT_MEMBERS_CTORS_1ST tag is set to YES then doxygen will sort the (brief and detailed) documentation of class members so that constructors and destructors are listed first. If set to NO (the default) the constructors will appear in the respective orders defined by SORT_MEMBER_DOCS and SORT_BRIEF_DOCS.

Note:
    If SORT_BRIEF_DOCS is set to NO this option is ignored for sorting brief member documentation. 
    If SORT_MEMBER_DOCS is set to NO this option is ignored for sorting detailed member documentation.
    [/code]

Here is an example where a sorted member function list would be nice: root.cern.ch/doc/master/classTGeoManager.html

[*]Finding methods of base classes: Please do not fold the inherited member functions. This prevents simple searching for text (via browser) to not find the method. I believe this is the relevant doxygen parameter

[code]
HTML_DYNAMIC_SECTIONS

If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML documentation will contain sections that can be hidden and shown after the page has loaded.

The default value is: NO.

This tag requires that the tag GENERATE_HTML is set to YES. [/code]

[*]What library does this class belong to? The old documentation had the header file and library the class can be found in. This was very handy.

Cheers,
Whit

2

Right now the Doxyfile we have for the ROOT reference guide contains:


# If the SORT_MEMBER_DOCS tag is set to YES then doxygen will sort the
# (detailed) documentation of file and class members alphabetically by member
# name. If set to NO the members will appear in declaration order.
# The default value is: YES.

SORT_MEMBER_DOCS       = YES

# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the brief
# descriptions of file, namespace and class members alphabetically by member
# name. If set to NO the members will appear in declaration order. Note that
# this will also influence the order of the classes in the class list.
# The default value is: NO.

SORT_BRIEF_DOCS        = NO

# If the SORT_MEMBERS_CTORS_1ST tag is set to YES then doxygen will sort the
# (brief and detailed) documentation of class members so that constructors and
# destructors are listed first. If set to NO the constructors will appear in the
# respective orders defined by SORT_BRIEF_DOCS and SORT_MEMBER_DOCS.
# Note: If SORT_BRIEF_DOCS is set to NO this option is ignored for sorting brief
# member documentation.
# Note: If SORT_MEMBER_DOCS is set to NO this option is ignored for sorting
# detailed member documentation.
# The default value is: NO.

SORT_MEMBERS_CTORS_1ST = NO

# If the SORT_GROUP_NAMES tag is set to YES then doxygen will sort the hierarchy
# of group names into alphabetical order. If set to NO the group names will
# appear in their defined order.
# The default value is: NO.

SORT_GROUP_NAMES       = NO

# If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be sorted by
# fully-qualified names, including namespaces. If set to NO, the class list will
# be sorted only by class name, not including the namespace part.
# Note: This option is not very useful if HIDE_SCOPE_NAMES is set to YES.
# Note: This option applies only to the class list, not to the alphabetical
# list.
# The default value is: NO.

SORT_BY_SCOPE_NAME     = NO

Only SORT_MEMBER_DOCS is set to YES. Do you suggest to also set all the others to YES ?

I agree with you about finding methods. Currently HTML_DYNAMIC_SECTIONS is set to NO in Doxyfile. I just tried to set it to YES. This does not help. Inherited member functions are still folded.

Note that you can see the current version of Doxyfile here:
root.cern.ch/gitweb?p=root.git; … le;hb=HEAD

Agreed. But I did not find yet the way to do it…any suggestion is welcome.

3

Hi

Doxygen has always been a struggle of trial and error for me, so I these are merely suggestions.

I think you want to change these two variables to yes:

SORT_BRIEF_DOCS        = YES
SORT_MEMBERS_CTORS_1ST = YES

This way the “brief”, which I think is just the initial list of members, will be sorted alphabetically.
The second puts the constructors at the top.

For the sections maybe you want to set this to no?

# Set the SUBGROUPING tag to YES to allow class member groups of the same type
# (for instance a group of public functions) to be put as a subgroup of that
# type (e.g. under the Public Functions section). Set it to NO to prevent
# subgrouping. Alternatively, this can be done per class using the
# \nosubgrouping command.
# The default value is: YES.

SUBGROUPING            = YES

Not sure what it will do…

From looking at the produced html, the dynsections.js does the folding. There seems to be no way to turn of the dynsections.js from the configuration…

Not sure about this, other than manually doing something…

Thanks for the quick reply.

Cheers,
Whit

4

I committed

SORT_BRIEF_DOCS        = YES
SORT_MEMBERS_CTORS_1ST = YES

but

SUBGROUPING            = YES

does not solve the issue we were talking about. I asked the Doxygen Forum.

5

I think the one we are look for is:

INLINE_INHERITED_MEMB

I will commit the change

6

Awesome! The alphabetized list of member functions looks great now.

Thank you. =D>

7

Thank you :slight_smile: . If you have more suggestions/ideas they are welcome.