Ticket #20 (closed defect: wontfix)

Opened 1 year ago

Last modified 3 months ago

Doxygen does not work

Reported by: Pse Assigned to: JJR
Priority: minor Milestone: Release 1.0
Component: Documentation Version: TRUNK
Keywords: Doxygen docs Cc:

Description (Last modified by Pse)

Support for Doxygen is currently broken. Potential reasons:

1. Comments are in the wrong format. Possibly, a small script to switch between Doxygen and DDoc style comments is needed.

2. Doxygen seems to hang indefinitely while computing class inheritance relations (duplicated/circular imports?).

Addtionally, TiMBuS was able to determine that "doxygen 'works' if you build docs for each subfolder separately. However this makes the output a little more messy, and there are a lot of blank linked packages..".

Change History

01/01/08 09:27:05 changed by Pse

  • description changed.

01/01/08 09:50:50 changed by Pse

  • description changed.

01/04/08 04:17:13 changed by TiMBuS

I decided to mess around with it today, to perhaps pinpoint the problem.

I simply removed and added folders from the src directory one at a time, checking to see if doxygen would work each time. I managed to get doxygen to complete by removing three folders: atk, gtkpixbuf, and gdk.

gdk seems to be the major offender. I've been mixing and matching it with other folders, and it seems to freeze doxygen indefinitely when used in conjunction with gtk or gtkc. Perhaps they are heavily imported by one another eventually causing cyclic inheritance too deep for doxygen to break out of?

As of typing the above, I removed all imports from all gdk files with a perl script, and doxygen completed. I hope this helps a bit.

Perhaps it might be a Good Thing to create an All.d file?

01/04/08 18:34:29 changed by Pse

Creating an all.d was briefly proposed by JJR in ticket #12 (I know, odd).

If what's stopping Doxygen from working turns out to be a circular inheritance problem, we're in for a rough ride, as I don't think we could solve that easily in gtkD. Thanks for your report, TiMBuS.

01/06/08 22:39:59 changed by TiMBuS

It's not really cyclic references that are the issue, rather just the complexity of having to follow the imports over and over to try and calculate the class inheritance.

I made an all.d file for each directory and changed the imports of each file with a perl hack. I also didn't declare the all.d files as modules, which stopped doxygen trying to follow them around, which solved the problem. The only issue is doxygen of course won't show you class inheritance which is a tad annoying, but it's still pretty good (and I don't think ddoc shows inheritance either).

I have a feeling that if you left doxygen for long enough (hours? days?) it would finish.

07/15/08 05:33:47 changed by okibi

Do we really need both ddoc and doxygen support? What's the difference? I've never actually attempted to use doxygen. I will look into this today.

07/15/08 17:51:22 changed by Mike Wey

One type of documentation should be enough.

08/22/08 14:42:27 changed by okibi

  • status changed from new to closed.
  • resolution set to wontfix.

Doxygen will not be included or supported.