-(grob-property-description 'X-extent-callback procedure? "procedure taking an grob and axis argument, returning a number-pair. The return value is the extent of the grob.")
-(grob-property-description 'X-offset-callbacks list? "list of functions, each taking an grob and axis argument. The function determine the position relative to this grob's parent. The last one in the list is called first.")
+(grob-property-description 'X-extent-callback procedure? "procedure taking an grob and axis argument, returning a number-pair. The return value is the extent of the grob.
+
+The size of a grob are determined through callbacks, settable with
+grob properties @code{X-extent-callback} and @code{Y-extent-callback}.
+There can be only one extent-callback for each axis. No callback
+(Scheme value @code{#f}) means: `empty in this direction'. If you fill
+in a pair of numbers, that pair hard-codes the extent in that
+coordinate.
+")
+(grob-property-description 'X-offset-callbacks list? "list of functions, each taking an grob and axis argument. The function determine the position relative to this grob's parent. The last one in the list is called first.
+
+Offsets of grobs are relative to a parent reference point. Most
+positions are not known when an object is created, so these are
+calculated as needed. This is done by adding a callback for a specific
+direction.
+
+Offset callbacks can be stacked, i.e.
+
+@example
+ \property .... \override #'Y-offset-callbacks = #(list
+ callback1 callback2 callback3)
+
+@end example
+
+The callbacks will be executed in the order @code{callback3 callback2
+callback1}. This is used for quantized positioning: the staccato dot is
+above or below a note head, and it must not be on a staff-line. To
+achieve this, the staccato dot has two callbacks: one that positions the
+grob above or below the note head, and one that rounds the Y-position of
+the grob to the nearest open space.
+
+
+")