Ticket #76 (closed defect: wontfix)

Opened 6 years ago

Last modified 2 years ago

Non-use of __HADDOCK__ flag is not documented

Reported by: SamB Owned by: waern
Priority: minor Milestone:
Version: Keywords:
Cc: SamB

Description

The documentation should mention that HADDOCK is no longer defined and is thus perfectly fine to use to protect Haddock 0.x from things it couldn't handle.

Change History

Changed 6 years ago by SamB

  • cc SamB added

Changed 5 years ago by waern

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

The manual doesn't mention the __HADDOCK__ macro and I don't think it should. This macro has never been defined by Haddock itself, AFAIK.

Changed 5 years ago by SamB

  • status changed from closed to reopened
  • resolution wontfix deleted

I think *that* should be documented in the manual. Macros with names of the form FOO have a strong tradition of being predefined by relevant systems; think of STDC, GNUC, and OBJC in the C world and GLASGOW_HASKELL, HUGS, and NHC in the Haskell world. Because of this tradition, explicitly documenting that Haddock does not define and has not ever defined HADDOCK would be a very good thing to do, and if there were a good reference about what *has* traditionally defined this macro, it would be desirable to direct people to that.

You can see what confusion not having this in the manual caused me!

Changed 5 years ago by SamB

Oops... all of those underlined things, like FOO, in the previous message are supposed to be more like __FOO__. Too bad I can't edit it :-(.

Changed 5 years ago by waern

  • owner set to waern
  • priority changed from major to minor
  • status changed from reopened to new

Alright, I can see the usefulness of documenting this.

Changed 2 years ago by anonymous

  • milestone 2.5.0 deleted

Milestone 2.5.0 deleted

Changed 2 years ago by SimonHengel

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

I agree that this would be useful. However, I don't know what/who previously defined __HADDOCK__, so I can't extend the documentation accordingly.

I still think it is not mandatory nor a defect, rather a nice to have.

I'll close this issue for now. If somebody is willing to do the research, please re-open *and* attach a patch.

Note: See TracTickets for help on using tickets.