[Doxygen-users] FW: source browser bug report and suggestion (resend)

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

This seemed to not get out the first time.  Let me try again.  --Darren

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

> 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