[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#9287: Mention `displayed-month' and `displayed-year' in `diary-mark-
bug#9287: Mention `displayed-month' and `displayed-year' in `diary-mark-entries-hook' documentation
Sun, 11 Sep 2011 05:02:58 +0200
Gnus/5.13 (Gnus v5.13) Emacs/24.0.50 (gnu/linux)
On Sun, 11 Sep 2011 04:11:25 +0200
Lars Magne Ingebrigtsen wrote:
> Štěpán Němec <address@hidden> writes:
>> The two variables, which fortunately do appear to be dynamically bound
>> to the middle month and year currently displayed in the calendar window
>> at the time of running `diary-mark-entries-hook', are _crucial_ for
>> being able to define useful marking functions. Please document this
>> (AFAICT they are currently not mentioned anywhere; I had to read much of
>> calendar.el and holidays.el to figure it out).
> Do you have a suggestion for a suitable documentation?
The variables definitely need docstrings explaining their use. There's
this comment in calendar.el:
;; A note on free variables:
;; The calendar passes around a few dynamically bound variables, which
;; unfortunately have rather common names. They are meant to be
;; available for external functions, so the names can't be changed.
;; displayed-month, displayed-year: bound in calendar-generate, the
;; central month of the 3 month calendar window
I'm hesitant as to the actual wording of such docstrings, because 1) my
uderstanding of the code is still quite limited, in particular I don't
know about _all_ the places the variables are bound and useful, and 2)
you probably couldn't use my wording anyway for so-called legal reasons.
I hoped Glenn (cc-ed) would take a look, as I think he is most familiar
with that part of Emacs.
The fact that the variables are bound should also be mentioned at least
in the `diary-mark-entries-hook' docstring.
It might be nice to add some info documentation, but given that there is
currently virtually no relevant documentation there to be found (even
`diary-mark-entries-hook' is only mentioned in a single code example),
I think just adding the docstrings would suffice.
Thank you for moving this issue forward.