[Doxygen-users] source browser bug report and suggestion

[Darren B. <db...@ga...>]

I have two comments on the source browser function, one a probable bug, the
second a change request which I'd like to propose to the community of users.

First, the bug report.  I believe I've found a bug in the source-browser
links in the raw code files.   Apparently, a link that should be of the form
"group page, anchor within group" is actually "file documentation page,
anchor within group", which sends the link off to random space in the file
documentation.

I have two source files, browser.dox and file.c.  All I did to the default
configuration file is turn on the source browser.

File.c is simple: routine1 and routine2 are in group1, routine3 and routine4
are in group2.  (I'm sending attachments separately, to hopefully keep this
message in plain text.  I honestly don't know what Outlook will do
otherwise.)

This produces a page for file.c's raw source, with hyperlinks in function
definitions, and references.  I copied and pasted a fragment below.
Internet Explorer expands some of the otherwise-hidden link information.

The links to the far left (lines 25, 38, 50, etc.) are fine.  I indeed have
two groups with two functions each.  What wasn't copied are the specific
anchors a0 and a1.  (The full link is of the form group_group1.html#a0.)

The problem is the links by function names, which all link to file_8c.html.
Again, what isn't shown is that each of these links has an anchor a0 and a1,
consistent with the routine's place in the group.  File_8c.html appears to
not have any anchors, so the link jumps to the top of the page.  In my
actual code, I think structures and other elements in the file do create
anchors, so the link jumps to an unrelated element in the same file.

Again, I think the fix would be rather simple.  All three links to routine1
would jump to the group page.  Although, this might get more complicated for
functions that are not in a group, but are documented due to @file
directives.

------------------
00025 <group__group1.html> int routine1 <file_8c.html>(int x)
00026 {
00027     return( x );
00028 }
00029 
00030 
00038 <group__group1.html> int routine2 <file_8c.html>(int x)
00039 {
00040     return( routine1 <file_8c.html>(x) );
00041 }
00042 
00050 <group__group2.html> int routine3 <file_8c.html>(int x)
00051 {
00052     return( x );
00053 }
00054 
00055 
00063 <group__group2.html> int routine4 <file_8c.html>(int x)
00064 {
00065     return( routine3 <file_8c.html>(x) );
00066 }
00067 
00068 
00069 

----------------

Second, I find the links in the browser a little counter-intuitive.  If I am
in documentation, and I follow a "referenced by" link, I jump to source
code.  If I am in source code, and I follow the link where one function
calls another, I jump back to an (incorrect) documentation page.   I
expected to see documentation "referenced by" links jump to documentation,
and source-code references jump to source code.  For any given function, I
can jump between code and documentation using the "Definition at line X"
link, and the line number in the left column of source code.

Any opinions?  I imagine this is only worth changing if there is a clear
consensus to do so.  Otherwise, so long as links go from source code to the
correct documentation, I can traverse a code tree easily enough.


Thanks,
   Darren