From 92e8f758e29427d28c413d1998c895b9c61932fd Mon Sep 17 00:00:00 2001 From: Werner Lemberg Date: Mon, 2 Jul 2007 11:53:23 +0200 Subject: [PATCH] Improve and correct documentation strings. --- lily/all-font-metrics-scheme.cc | 4 +- lily/axis-group-interface-scheme.cc | 4 +- lily/book-scheme.cc | 20 ++++--- lily/context-scheme.cc | 44 +++++++-------- lily/dimensions-scheme.cc | 10 ++-- lily/dispatcher-scheme.cc | 12 ++--- lily/duration-scheme.cc | 31 +++++------ lily/engraver.cc | 10 ++-- lily/file-name-map.cc | 2 +- lily/font-config-scheme.cc | 2 +- lily/font-metric-scheme.cc | 34 ++++++------ lily/function-documentation.cc | 2 +- lily/general-scheme.cc | 78 ++++++++++++++------------- lily/global-context-scheme.cc | 34 ++++++------ lily/grob-array-scheme.cc | 4 +- lily/grob-pq-engraver.cc | 3 +- lily/grob-property.cc | 29 +++++----- lily/grob-scheme.cc | 57 ++++++++++---------- lily/identifier-smob.cc | 4 +- lily/input-scheme.cc | 12 +++-- lily/item-scheme.cc | 5 +- lily/lily-lexer-scheme.cc | 3 +- lily/lily-parser-scheme.cc | 20 +++---- lily/ly-module.cc | 2 +- lily/module-scheme.cc | 12 ++--- lily/moment-scheme.cc | 14 +++-- lily/music-function-scheme.cc | 13 ++--- lily/music-scheme.cc | 52 +++++++++--------- lily/note-head-scheme.cc | 4 +- lily/open-type-font-scheme.cc | 14 ++--- lily/output-def-scheme.cc | 21 ++++---- lily/page-breaking-scheme.cc | 10 ++-- lily/pango-font-scheme.cc | 2 +- lily/pango-select-scheme.cc | 3 +- lily/paper-book-scheme.cc | 6 +-- lily/paper-outputter-scheme.cc | 4 +- lily/paper-score-scheme.cc | 3 +- lily/performance-scheme.cc | 2 +- lily/pfb-scheme.cc | 4 +- lily/pitch-scheme.cc | 33 ++++++------ lily/prob-scheme.cc | 12 ++--- lily/profile.cc | 5 +- lily/program-option-scheme.cc | 8 +-- lily/scale.cc | 2 +- lily/scheme-listener-scheme.cc | 7 ++- lily/score-scheme.cc | 14 ++--- lily/script-column.cc | 2 +- lily/simple-closure.cc | 13 ++--- lily/simple-spacer-scheme.cc | 20 ++++--- lily/smobs.cc | 2 +- lily/spanner-scheme.cc | 6 +-- lily/stencil-scheme.cc | 83 +++++++++++++++-------------- lily/stream-event-scheme.cc | 9 ++-- lily/system-scheme.cc | 10 ++-- lily/text-interface.cc | 17 +++--- lily/text-metrics.cc | 3 +- lily/translator-ctors.cc | 3 +- lily/translator-scheme.cc | 6 +-- lily/translator.cc | 3 +- scm/documentation-lib.scm | 8 ++- 60 files changed, 443 insertions(+), 413 deletions(-) diff --git a/lily/all-font-metrics-scheme.cc b/lily/all-font-metrics-scheme.cc index 793b4c5875..a3b19e468d 100644 --- a/lily/all-font-metrics-scheme.cc +++ b/lily/all-font-metrics-scheme.cc @@ -13,7 +13,7 @@ LY_DEFINE (ly_reset_all_fonts, "ly:reset-all-fonts", 0, 0, 0, (), - "Forget all about previously loaded fonts. ") + "Forget all about previously loaded fonts.") { delete all_fonts_global; all_fonts_global = new All_font_metrics (global_path.to_string ()); @@ -24,7 +24,7 @@ LY_DEFINE (ly_reset_all_fonts, "ly:reset-all-fonts", 0, 0, 0, LY_DEFINE (ly_font_load, "ly:font-load", 1, 0, 0, (SCM name), - "Load the font @var{name}. ") + "Load the font @var{name}.") { LY_ASSERT_TYPE (scm_is_string, name, 1); diff --git a/lily/axis-group-interface-scheme.cc b/lily/axis-group-interface-scheme.cc index 3b529ed34e..45236e6ca5 100644 --- a/lily/axis-group-interface-scheme.cc +++ b/lily/axis-group-interface-scheme.cc @@ -13,8 +13,8 @@ LY_DEFINE (ly_relative_group_extent, "ly:relative-group-extent", 3, 0, 0, (SCM elements, SCM common, SCM axis), - "Determine the extent of @var{elements} relative to @var{common} in the " - "@var{axis} direction.") + "Determine the extent of @var{elements} relative to @var{common} in the" + " @var{axis} direction.") { Grob_array *ga = unsmob_grob_array (elements); diff --git a/lily/book-scheme.cc b/lily/book-scheme.cc index 567504cf07..e00f1ded49 100644 --- a/lily/book-scheme.cc +++ b/lily/book-scheme.cc @@ -15,8 +15,8 @@ LY_DEFINE (ly_make_book, "ly:make-book", 2, 0, 1, (SCM paper, SCM header, SCM scores), - "Make a \\book of @var{paper} and @var{header} (which may be #f as well) " - "containing @code{\\scores}.") + "Make a @code{\\book} of @var{paper} and @var{header}" + " (which may be @code{#f} as well) containing @code{\\scores}.") { Output_def *odef = unsmob_output_def (paper); LY_ASSERT_SMOB (Output_def, paper, 1); @@ -39,10 +39,9 @@ LY_DEFINE (ly_book_process, "ly:book-process", SCM default_paper, SCM default_layout, SCM output), - "Print book. @var{output} is passed to the backend unchanged. " - "Eg. it may be " - "a string (for file based outputs) or a socket (for network based " - "output).") + "Print book. @var{output} is passed to the backend unchanged." + " For example, it may be a string (for file based outputs)" + " or a socket (for network based output).") { Book *book = unsmob_book (book_smob); @@ -67,10 +66,9 @@ LY_DEFINE (ly_book_process_to_systems, "ly:book-process-to-systems", SCM default_paper, SCM default_layout, SCM output), - "Print book. @var{output} is passed to the backend unchanged. " - "Eg. it may be " - "a string (for file based outputs) or a socket (for network based " - "output).") + "Print book. @var{output} is passed to the backend unchanged." + " For example, it may be a string (for file based outputs)" + " or a socket (for network based output).") { LY_ASSERT_SMOB (Book, book_smob, 1); LY_ASSERT_SMOB (Output_def, default_paper, 2); @@ -91,7 +89,7 @@ LY_DEFINE (ly_book_process_to_systems, "ly:book-process-to-systems", LY_DEFINE (ly_book_add_score_x, "ly:book-add-score!", 2, 0, 0, (SCM book_smob, SCM score), - "Add @var{score} to @var{book_smob} score list.") + "Add @var{score} to @var{book-smob} score list.") { LY_ASSERT_SMOB (Book, book_smob, 1); Book *book = unsmob_book (book_smob); diff --git a/lily/context-scheme.cc b/lily/context-scheme.cc index 4ff48155e3..d4289d7bcc 100644 --- a/lily/context-scheme.cc +++ b/lily/context-scheme.cc @@ -13,9 +13,9 @@ LY_DEFINE (ly_context_id, "ly:context-id", 1, 0, 0, (SCM context), - "Return the id string of @var{context}, " - "i.e. for @code{\\context Voice = one .. } " - "return the string @code{one}.") + "Return the ID string of @var{context}," + " i.e., for @code{\\context Voice = one @dots{}}" + " return the string @code{one}.") { Context *tr = unsmob_context (context); @@ -26,9 +26,9 @@ LY_DEFINE (ly_context_id, "ly:context-id", LY_DEFINE (ly_context_name, "ly:context-name", 1, 0, 0, (SCM context), - "Return the name of @var{context}, " - "i.e. for @code{\\context Voice = one .. } " - "return the symbol @code{Voice}.") + "Return the name of @var{context}," + " i.e., for @code{\\context Voice = one @dots{}}" + " return the symbol @code{Voice}.") { LY_ASSERT_SMOB (Context, context, 1); @@ -39,8 +39,8 @@ LY_DEFINE (ly_context_name, "ly:context-name", LY_DEFINE (ly_context_grob_definition, "ly:context-grob-definition", 2, 0, 0, (SCM context, SCM name), - "Return the definition of @var{name} (a symbol) within @var{context} " - "as an alist") + "Return the definition of @var{name} (a symbol) within" + " @var{context} as an alist.") { Context *tr = unsmob_context (context); @@ -52,10 +52,10 @@ LY_DEFINE (ly_context_grob_definition, "ly:context-grob-definition", LY_DEFINE (ly_context_pushpop_property, "ly:context-pushpop-property", 3, 1, 0, (SCM context, SCM grob, SCM eltprop, SCM val), - "Do a single @code{\\override} or @code{\\revert} operation " - "in @var{context}. The grob definition @code{grob} is extended " - "with @code{eltprop} (if @var{val} is specified) " - "or reverted (if unspecified).") + "Do a single @code{\\override} or @code{\\revert} operation" + " in @var{context}. The grob definition @var{grob} is extended" + " with @var{eltprop} (if @var{val} is specified) or reverted" + " (if unspecified).") { Context *tg = unsmob_context (context); @@ -70,7 +70,7 @@ LY_DEFINE (ly_context_pushpop_property, "ly:context-pushpop-property", LY_DEFINE (ly_context_property, "ly:context-property", 2, 0, 0, (SCM c, SCM name), - "Return the value of @var{name} from context @var{c}") + "Return the value of @var{name} from context @var{c}.") { LY_ASSERT_SMOB (Context, c, 1); LY_ASSERT_TYPE (ly_is_symbol, name, 2); @@ -81,8 +81,8 @@ LY_DEFINE (ly_context_property, "ly:context-property", LY_DEFINE (ly_context_set_property_x, "ly:context-set-property!", 3, 0, 0, (SCM context, SCM name, SCM val), - "Set value of property @var{name} in context @var{context} " - "to @var{val}.") + "Set value of property @var{name} in context @var{context}" + " to @var{val}.") { LY_ASSERT_SMOB (Context, context, 1); LY_ASSERT_TYPE (ly_is_symbol, name, 2); @@ -96,8 +96,8 @@ LY_DEFINE (ly_context_set_property_x, "ly:context-set-property!", LY_DEFINE (ly_context_property_where_defined, "ly:context-property-where-defined", 2, 0, 0, (SCM context, SCM name), - "Return the context above @var{context} " - "where @var{name} is defined.") + "Return the context above @var{context}" + " where @var{name} is defined.") { LY_ASSERT_SMOB (Context, context, 1); LY_ASSERT_TYPE (ly_is_symbol, name, 2); @@ -141,8 +141,8 @@ LY_DEFINE (ly_context_parent, "ly:context-parent", /* FIXME: todo: should support translator IDs, and creation? */ LY_DEFINE (ly_context_find, "ly:context-find", 2, 0, 0, (SCM context, SCM name), - "Find a parent of @var{context} that has name or alias @var{name}. " - "Return @code{#f} if not found.") + "Find a parent of @var{context} that has name or alias @var{name}." + " Return @code{#f} if not found.") { LY_ASSERT_SMOB (Context, context, 1); LY_ASSERT_TYPE (ly_is_symbol, name, 2); @@ -160,7 +160,7 @@ LY_DEFINE (ly_context_find, "ly:context-find", LY_DEFINE (ly_context_now, "ly:context-now", 1, 0, 0, (SCM context), - "Return now-moment of context CONTEXT") + "Return @code{now-moment} of context @var{context}.") { LY_ASSERT_SMOB (Context, context, 1); Context *ctx = unsmob_context (context); @@ -169,7 +169,7 @@ LY_DEFINE (ly_context_now, "ly:context-now", LY_DEFINE (ly_context_event_source, "ly:context-event-source", 1, 0, 0, (SCM context), - "Return event-source of context CONTEXT") + "Return @code{event-source} of context @var{context}.") { LY_ASSERT_SMOB (Context, context, 1); Context *ctx = unsmob_context (context); @@ -178,7 +178,7 @@ LY_DEFINE (ly_context_event_source, "ly:context-event-source", LY_DEFINE (ly_context_events_below, "ly:context-events-below", 1, 0, 0, (SCM context), - "Return a stream-distributor that distributes all events\n" + "Return a @code{stream-distributor} that distributes all events" " from @var{context} and all its subcontexts.") { LY_ASSERT_SMOB (Context, context, 1); diff --git a/lily/dimensions-scheme.cc b/lily/dimensions-scheme.cc index 4025b4078a..c64b901f8f 100644 --- a/lily/dimensions-scheme.cc +++ b/lily/dimensions-scheme.cc @@ -12,7 +12,7 @@ LY_DEFINE (ly_pt, "ly:pt", 1, 0, 0, (SCM num), - "@var{num} printer points") + "@var{num} printer points.") { LY_ASSERT_TYPE (scm_is_number, num, 1); return scm_from_double (point_constant @@ -21,7 +21,7 @@ LY_DEFINE (ly_pt, "ly:pt", LY_DEFINE (ly_cm, "ly:cm", 1, 0, 0, (SCM num), - "@var{num} cm") + "@var{num} cm.") { LY_ASSERT_TYPE (scm_is_number, num, 1); return scm_from_double (cm_constant @@ -30,7 +30,7 @@ LY_DEFINE (ly_cm, "ly:cm", LY_DEFINE (ly_inch, "ly:inch", 1, 0, 0, (SCM num), - "@var{num} inches") + "@var{num} inches.") { LY_ASSERT_TYPE (scm_is_number, num, 1); return scm_from_double (inch_constant @@ -39,7 +39,7 @@ LY_DEFINE (ly_inch, "ly:inch", LY_DEFINE (ly_mm, "ly:mm", 1, 0, 0, (SCM num), - "@var{num} mm") + "@var{num} mm.") { LY_ASSERT_TYPE (scm_is_number, num, 1); return scm_from_double (mm_constant @@ -48,7 +48,7 @@ LY_DEFINE (ly_mm, "ly:mm", LY_DEFINE (ly_bp, "ly:bp", 1, 0, 0, (SCM num), - "@var{num} bigpoints (1/72th inch)") + "@var{num} bigpoints (1/72th inch).") { LY_ASSERT_TYPE (scm_is_number, num, 1); return scm_from_double (bigpoint_constant diff --git a/lily/dispatcher-scheme.cc b/lily/dispatcher-scheme.cc index e467064bf4..5f0acb229d 100644 --- a/lily/dispatcher-scheme.cc +++ b/lily/dispatcher-scheme.cc @@ -10,14 +10,14 @@ LY_DEFINE (ly_make_dispatcher, "ly:make-dispatcher", 0, 0, 0, (), - "Returns a newly created dispatcher.") + "Return a newly created dispatcher.") { return (new Dispatcher ())->unprotect (); } LY_DEFINE (ly_connect_dispatchers, "ly:connect-dispatchers", 2, 0, 0, (SCM to, SCM from), - "Makes the dispatcher @var{to} listen to events from @var{from}." ) + "Make the dispatcher @var{to} listen to events from @var{from}.") { Dispatcher *t = unsmob_dispatcher (to); Dispatcher *f = unsmob_dispatcher (from); @@ -32,8 +32,9 @@ LY_DEFINE (ly_connect_dispatchers, "ly:connect-dispatchers", LY_DEFINE (ly_add_listener, "ly:add-listener", 2, 0, 1, (SCM list, SCM disp, SCM cl), - "Adds the listener @var{list} to the dispatcher @var{disp}.\n" - " Whenever @var{disp} hears an event of class @var{cl}, it will be forwarded to @var{list}.\n" ) + "Add the listener @var{list} to the dispatcher @var{disp}." + " Whenever @var{disp} hears an event of class @var{cl}," + " it is forwarded to @var{list}.") { Listener *l = unsmob_listener (list); Dispatcher *d = unsmob_dispatcher (disp); @@ -53,8 +54,7 @@ LY_DEFINE (ly_add_listener, "ly:add-listener", LY_DEFINE (ly_broadcast, "ly:broadcast", 2, 0, 0, (SCM disp, SCM ev), - "Sends the stream event @var{ev} to the dispatcher\n" - "@var{disp}.") + "Send the stream event @var{ev} to the dispatcher @var{disp}.") { Dispatcher *d = unsmob_dispatcher (disp); Stream_event *e = unsmob_stream_event (ev); diff --git a/lily/duration-scheme.cc b/lily/duration-scheme.cc index f62bba582a..d371475581 100644 --- a/lily/duration-scheme.cc +++ b/lily/duration-scheme.cc @@ -41,17 +41,17 @@ LY_DEFINE (ly_duration_less_p, "ly:durationduration_log ()); @@ -96,7 +96,7 @@ LY_DEFINE (ly_duration_log, "ly:duration-log", LY_DEFINE (ly_duration_dot_count, "ly:duration-dot-count", 1, 0, 0, (SCM dur), - "Extract the dot count from @var{dur}") + "Extract the dot count from @var{dur}.") { LY_ASSERT_SMOB (Duration, dur, 1); return scm_from_int (unsmob_duration (dur)->dot_count ()); @@ -113,7 +113,7 @@ LY_DEFINE (ly_intlog2, "ly:intlog2", LY_DEFINE (ly_duration_length, "ly:duration-length", 1, 0, 0, (SCM dur), - "The length of the duration as a Moment.") + "The length of the duration as a @code{moment}.") { LY_ASSERT_SMOB (Duration, dur, 1); return Moment (unsmob_duration (dur)->get_length ()).smobbed_copy (); @@ -121,7 +121,7 @@ LY_DEFINE (ly_duration_length, "ly:duration-length", LY_DEFINE (ly_duration_2_string, "ly:duration->string", 1, 0, 0, (SCM dur), - "Convert @var{dur} to string.") + "Convert @var{dur} to a string.") { LY_ASSERT_SMOB (Duration, dur, 1); return ly_string2scm (unsmob_duration (dur)->to_string ()); @@ -129,7 +129,8 @@ LY_DEFINE (ly_duration_2_string, "ly:duration->string", LY_DEFINE (ly_duration_factor, "ly:duration-factor", 1, 0, 0, (SCM dur), - "Extract the compression factor from @var{dur}. Return as a pair.") + "Extract the compression factor from @var{dur}." + " Return it as a pair.") { LY_ASSERT_SMOB (Duration, dur, 1); Rational r = unsmob_duration (dur)->factor (); diff --git a/lily/engraver.cc b/lily/engraver.cc index 84780dd0a2..70a8bf512f 100644 --- a/lily/engraver.cc +++ b/lily/engraver.cc @@ -90,11 +90,11 @@ Engraver::Engraver () static SCM creation_callback = SCM_EOL; LY_DEFINE (ly_set_grob_creation_callback, "ly:set-grob-creation-callback", 1, 0, 0, (SCM cb), - "Specify a procedure that will be called every time a new grob " - "is created. The callback will receive as arguments the grob " - "that was created, the name of the C++ source file that caused " - "the grob to be created and the corresponding line number in the " - "C++ source file.") + "Specify a procedure that will be called every time a new grob" + " is created. The callback will receive as arguments the grob" + " that was created, the name of the C++ source file that caused" + " the grob to be created, and the corresponding line number in" + " the C++ source file.") { LY_ASSERT_TYPE (ly_is_procedure, cb, 1); diff --git a/lily/file-name-map.cc b/lily/file-name-map.cc index 3f6939c1ff..61bad60423 100644 --- a/lily/file-name-map.cc +++ b/lily/file-name-map.cc @@ -24,7 +24,7 @@ map_file_name (string s) LY_DEFINE (ly_add_file_name_alist, "ly:add-file-name-alist", 1, 0, 0, (SCM alist), - "Add mappings for error messages from specified alist") + "Add mappings for error messages from @var{alist}.") { for (SCM s = alist; scm_is_pair (s); s = scm_cdr (s)) { diff --git a/lily/font-config-scheme.cc b/lily/font-config-scheme.cc index 6ccc616793..79f074cef8 100644 --- a/lily/font-config-scheme.cc +++ b/lily/font-config-scheme.cc @@ -87,7 +87,7 @@ display_list (FcConfig *fcc) LY_DEFINE (ly_font_config_get_font_file, "ly:font-config-get-font-file", 1, 0, 0, (SCM name), - "Get the file for font @var{name}") + "Get the file for font @var{name}.") { LY_ASSERT_TYPE (scm_is_string, name, 1); diff --git a/lily/font-metric-scheme.cc b/lily/font-metric-scheme.cc index aa49a29e23..88cfc58e2b 100644 --- a/lily/font-metric-scheme.cc +++ b/lily/font-metric-scheme.cc @@ -15,9 +15,9 @@ LY_DEFINE (ly_font_get_glyph, "ly:font-get-glyph", 2, 0, 0, (SCM font, SCM name), - "Return a Stencil from @var{font} for the glyph named @var{name}. " - "@var{font} must be available as an AFM file. If the glyph " - "is not available, return @code{#f}.") + "Return a stencil from @var{font} for the glyph named @var{name}." + " @var{font} must be available as an AFM file. If the glyph" + " is not available, return @code{#f}.") { Font_metric *fm = unsmob_metrics (font); LY_ASSERT_SMOB (Font_metric, font, 1); @@ -32,8 +32,8 @@ LY_DEFINE (ly_font_get_glyph, "ly:font-get-glyph", LY_DEFINE (ly_get_glyph, "ly:get-glyph", 2, 0, 0, (SCM font, SCM index), - "Retrieve a Stencil for the glyph numbered @var{index} " - "in @var{font}.") + "Retrieve a stencil for the glyph numbered @var{index}" + " in @var{font}.") { Font_metric *fm = unsmob_metrics (font); LY_ASSERT_SMOB (Font_metric, font, 1); @@ -57,7 +57,7 @@ LY_DEFINE (ly_font_glyph_name_to_index, "ly:font-glyph-name-to-index", LY_DEFINE (ly_font_index_to_charcode, "ly:font-index-to-charcode", 2, 0, 0, (SCM font, SCM index), - "Return the character code for @var{index} @var{font}.") + "Return the character code for @var{index} in @var{font}.") { Font_metric *fm = unsmob_metrics (font); LY_ASSERT_SMOB (Font_metric, font, 1); @@ -81,9 +81,9 @@ LY_DEFINE (ly_font_glyph_name_to_charcode, "ly:font-glyph-name-to-charcode", LY_DEFINE (ly_text_dimension, "ly:text-dimension", 2, 0, 0, (SCM font, SCM text), - "Given the font metric in @var{font} and the string @var{text}, " - "compute the extents of that text in that font. " - "The return value is a pair of number-pairs.") + "Given the font metric in @var{font} and the string @var{text}," + " compute the extents of that text in that font. The return" + " value is a pair of number-pairs.") { Box b; Modified_font_metric *fm = dynamic_cast @@ -103,8 +103,8 @@ LY_DEFINE (ly_text_dimension, "ly:text-dimension", LY_DEFINE (ly_font_file_name, "ly:font-file-name", 1, 0, 0, (SCM font), - "Given the font metric @var{font}, " - "return the corresponding file name.") + "Given the font metric @var{font}," + " return the corresponding file name.") { LY_ASSERT_SMOB (Font_metric, font, 1); @@ -117,8 +117,8 @@ LY_DEFINE (ly_font_file_name, "ly:font-file-name", LY_DEFINE (ly_font_name, "ly:font-name", 1, 0, 0, (SCM font), - "Given the font metric @var{font}, " - "return the corresponding name.") + "Given the font metric @var{font}," + " return the corresponding name.") { LY_ASSERT_SMOB (Font_metric, font, 1); Font_metric *fm = unsmob_metrics (font); @@ -128,8 +128,8 @@ LY_DEFINE (ly_font_name, "ly:font-name", LY_DEFINE (ly_font_magnification, "ly:font-magnification", 1, 0, 0, (SCM font), - "Given the font metric @var{font}, return the " - "magnification, relative to the current output-scale.") + "Given the font metric @var{font}, return the" + " magnification, relative to the current output-scale.") { LY_ASSERT_SMOB (Font_metric, font, 1); @@ -139,8 +139,8 @@ LY_DEFINE (ly_font_magnification, "ly:font-magnification", 1, 0, 0, LY_DEFINE (ly_font_design_size, "ly:font-design-size", 1, 0, 0, (SCM font), - "Given the font metric @var{font}, return the " - "design size, relative to the current output-scale.") + "Given the font metric @var{font}, return the" + " design size, relative to the current output-scale.") { LY_ASSERT_SMOB (Font_metric, font, 1); diff --git a/lily/function-documentation.cc b/lily/function-documentation.cc index c5b1387726..909eb1030b 100644 --- a/lily/function-documentation.cc +++ b/lily/function-documentation.cc @@ -50,7 +50,7 @@ ly_add_function_documentation (SCM func, LY_DEFINE (ly_get_all_function_documentation, "ly:get-all-function-documentation", 0, 0, 0, (), - "Get a hash table with all lilypond Scheme extension functions.") + "Get a hash table with all LilyPond Scheme extension functions.") { return doc_hash_table; } diff --git a/lily/general-scheme.cc b/lily/general-scheme.cc index 48ee4503b1..7d4b5c1c30 100644 --- a/lily/general-scheme.cc +++ b/lily/general-scheme.cc @@ -29,7 +29,8 @@ using namespace std; LY_DEFINE (ly_start_environment, "ly:start-environment", 0, 0, 0, (), - "Return the environment, a list of strings, that was in effect at program start") + "Return the environment (a list of strings) that was in" + " effect at program start.") { SCM l = SCM_EOL; SCM *tail = &l; @@ -47,8 +48,8 @@ LY_DEFINE (ly_start_environment, "ly:start-environment", LY_DEFINE (ly_find_file, "ly:find-file", 1, 0, 0, (SCM name), - "Return the absolute file name of @var{name}, " - "or @code{#f} if not found.") + "Return the absolute file name of @var{name}," + " or @code{#f} if not found.") { LY_ASSERT_TYPE (scm_is_string, name, 1); @@ -66,8 +67,8 @@ LY_DEFINE (ly_find_file, "ly:find-file", */ LY_DEFINE (ly_gulp_file, "ly:gulp-file", 1, 1, 0, (SCM name, SCM size), - "Read the file @var{name}, and return its contents in a string. " - "The file is looked up using the search path. ") + "Read the file @var{name}, and return its contents in a string." + " The file is looked up using the search path.") { LY_ASSERT_TYPE (scm_is_string, name, 1); int sz = INT_MAX; @@ -83,8 +84,8 @@ LY_DEFINE (ly_gulp_file, "ly:gulp-file", LY_DEFINE (ly_error, "ly:error", 1, 0, 1, (SCM str, SCM rest), - "Scheme callable function to issue the error @code{msg}. " - "The error is formatted with @code{format} and @code{rest}.") + "A Scheme callable function to issue the error @var{str}." + " The error is formatted with @code{format} and @var{rest}.") { LY_ASSERT_TYPE (scm_is_string, str, 1); str = scm_simple_format (SCM_BOOL_F, str, rest); @@ -94,8 +95,8 @@ LY_DEFINE (ly_error, "ly:error", LY_DEFINE (ly_message, "ly:message", 1, 0, 1, (SCM str, SCM rest), - "Scheme callable function to issue the message @code{msg}. " - "The message is formatted with @code{format} and @code{rest}.") + "A Scheme callable function to issue the message @var{str}." + " The message is formatted with @code{format} and @var{rest}.") { LY_ASSERT_TYPE (scm_is_string, str, 1); str = scm_simple_format (SCM_BOOL_F, str, rest); @@ -105,8 +106,8 @@ LY_DEFINE (ly_message, "ly:message", LY_DEFINE (ly_progress, "ly:progress", 1, 0, 1, (SCM str, SCM rest), - "Scheme callable function to print progress @code{str}. " - "The message is formatted with @code{format} and @code{rest}.") + "A Scheme callable function to print progress @var{str}." + " The message is formatted with @code{format} and @var{rest}.") { LY_ASSERT_TYPE (scm_is_string, str, 1); str = scm_simple_format (SCM_BOOL_F, str, rest); @@ -116,8 +117,9 @@ LY_DEFINE (ly_progress, "ly:progress", LY_DEFINE (ly_programming_error, "ly:programming-error", 1, 0, 1, (SCM str, SCM rest), - "Scheme callable function to issue the warning @code{msg}. " - "The message is formatted with @code{format} and @code{rest}.") + "A Scheme callable function to issue the internal warning" + " @var{str}. The message is formatted with @code{format}" + " and @var{rest}.") { LY_ASSERT_TYPE (scm_is_string, str, 1); str = scm_simple_format (SCM_BOOL_F, str, rest); @@ -127,8 +129,8 @@ LY_DEFINE (ly_programming_error, "ly:programming-error", LY_DEFINE (ly_warning, "ly:warning", 1, 0, 1, (SCM str, SCM rest), - "Scheme callable function to issue the warning @code{str}. " - "The message is formatted with @code{format} and @code{rest}.") + "A Scheme callable function to issue the warning @code{str}." + " The message is formatted with @code{format} and @code{rest}.") { LY_ASSERT_TYPE (scm_is_string, str, 1); str = scm_simple_format (SCM_BOOL_F, str, rest); @@ -138,9 +140,9 @@ LY_DEFINE (ly_warning, "ly:warning", LY_DEFINE (ly_dir_p, "ly:dir?", 1, 0, 0, (SCM s), - "type predicate. A direction is @code{-1}, @code{0} or " - "@code{1}, where @code{-1} represents " - "left or down and @code{1} represents right or up.") + "A type predicate. The direction@tie{}@code{s} is @code{-1}," + " @code{0} or@tie{}@code{1}, where @code{-1} represents" + " left or down and @code{1} represents right or up.") { if (scm_is_number (s)) { @@ -153,8 +155,8 @@ LY_DEFINE (ly_dir_p, "ly:dir?", LY_DEFINE (ly_assoc_get, "ly:assoc-get", 2, 1, 0, (SCM key, SCM alist, SCM default_value), - "Return value if KEY in ALIST, else DEFAULT-VALUE " - "(or #f if not specified).") + "Return value if @var{key} in @var{alist}, else @code{default-value}" + " (or @code{#f} if not specified).") { LY_ASSERT_TYPE(ly_cheap_is_list, alist, 2); @@ -170,7 +172,8 @@ LY_DEFINE (ly_assoc_get, "ly:assoc-get", LY_DEFINE (ly_string_substitute, "ly:string-substitute", 3, 0, 0, (SCM a, SCM b, SCM s), - "Replace string @var{a} by string @var{b} in string @var{s}.") + "Replace string@tie{}@var{a} by string@tie{}@var{b} in" + " string@tie{}@var{s}.") { LY_ASSERT_TYPE (scm_is_string, s, 1); LY_ASSERT_TYPE (scm_is_string, b, 2); @@ -210,7 +213,8 @@ LY_DEFINE (ly_number_2_string, "ly:number->string", } LY_DEFINE (ly_version, "ly:version", 0, 0, 0, (), - "Return the current lilypond version as a list, e.g. @code{(1 3 127 uu1)}. ") + "Return the current lilypond version as a list, e.g.," + " @code{(1 3 127 uu1)}.") { char const *vs = "\'(" MAJOR_VERSION " " MINOR_VERSION " " PATCH_LEVEL " " MY_PATCH_LEVEL ")"; @@ -224,8 +228,8 @@ LY_DEFINE (ly_unit, "ly:unit", 0, 0, 0, (), } LY_DEFINE (ly_dimension_p, "ly:dimension?", 1, 0, 0, (SCM d), - "Return @var{d} is a number. Used to distinguish length " - "variables from normal numbers.") + "Return @var{d} as a number. Used to distinguish length" + " variables from normal numbers.") { return scm_number_p (d); } @@ -242,7 +246,7 @@ LY_DEFINE (ly_protects, "ly:protects", LY_DEFINE (ly_gettext, "ly:gettext", 1, 0, 0, (SCM string), - "Gettext wrapper.") + "A Scheme wrapper function for @code{gettext}.") { LY_ASSERT_TYPE (scm_is_string, string, 1); return ly_string2scm (_ (scm_i_string_chars (string))); @@ -250,8 +254,8 @@ LY_DEFINE (ly_gettext, "ly:gettext", LY_DEFINE (ly_output_formats, "ly:output-formats", 0, 0, 0, (), - "Formats passed to --format as a list of strings, " - "used for the output.") + "Formats passed to @option{--format} as a list of strings," + " used for the output.") { vector output_formats = string_split (output_format_global, ','); @@ -265,7 +269,7 @@ LY_DEFINE (ly_output_formats, "ly:output-formats", LY_DEFINE (ly_wide_char_2_utf_8, "ly:wide-char->utf-8", 1, 0, 0, (SCM wc), - "Encode the Unicode codepoint @var{wc}, an integer, as UTF-8") + "Encode the Unicode codepoint @var{wc}, an integer, as UTF-8.") { char buf[5]; @@ -307,9 +311,9 @@ LY_DEFINE (ly_effective_prefix, "ly:effective-prefix", LY_DEFINE (ly_chain_assoc_get, "ly:chain-assoc-get", 2, 1, 0, (SCM key, SCM achain, SCM dfault), - "Return value for @var{key} from a list of alists @var{achain}. " - "If no if no entry is found, return DFAULT, " - "or #f if no DFAULT not specified.") + "Return value for @var{key} from a list of alists @var{achain}." + " If no entry is found, return @var{dfault} or @code{#f} if no" + " @var{dfault} is specified.") { if (scm_is_pair (achain)) { @@ -325,7 +329,7 @@ LY_DEFINE (ly_chain_assoc_get, "ly:chain-assoc-get", LY_DEFINE (ly_stderr_redirect, "ly:stderr-redirect", 1, 1, 0, (SCM file_name, SCM mode), - "Redirect stderr to FILE-NAME, opened with MODE.") + "Redirect stderr to @var{file-name}, opened with @var{mode}.") { LY_ASSERT_TYPE (scm_is_string, file_name, 1); @@ -349,7 +353,7 @@ accumulate_symbol (void *closure, SCM key, SCM val, SCM result) LY_DEFINE (ly_hash_table_keys, "ly:hash-table-keys", 1,0,0, (SCM tab), - "return a list of keys in @var{tab}") + "Return a list of keys in @var{tab}.") { return scm_internal_hash_fold ((Hash_closure_function) & accumulate_symbol, NULL, SCM_EOL, tab); @@ -357,7 +361,7 @@ LY_DEFINE (ly_hash_table_keys, "ly:hash-table-keys", LY_DEFINE (ly_camel_case_2_lisp_identifier, "ly:camel-case->lisp-identifier", 1, 0, 0, (SCM name_sym), - "Convert FooBar_Bla to foo-bar-bla style symbol.") + "Convert @code{FooBar_Bla} to @code{foo-bar-bla} style symbol.") { LY_ASSERT_TYPE (ly_is_symbol, name_sym, 1); @@ -373,7 +377,7 @@ LY_DEFINE (ly_camel_case_2_lisp_identifier, "ly:camel-case->lisp-identifier", LY_DEFINE (ly_expand_environment, "ly:expand-environment", 1, 0, 0, (SCM str), - "Expand $VAR and $@{VAR@} in @var{str}.") + "Expand @code{$VAR} and @code{$@{VAR@}} in @var{str}.") { LY_ASSERT_TYPE (scm_is_string, str, 1); @@ -383,7 +387,7 @@ LY_DEFINE (ly_expand_environment, "ly:expand-environment", LY_DEFINE (ly_truncate_list_x, "ly:truncate-list!", 2, 0, 0, (SCM lst, SCM i), - "Take at most the first @var{i} of list @var{lst}") + "Take at most the first @var{i} of list @var{lst}.") { LY_ASSERT_TYPE (scm_is_integer, i, 1); @@ -438,7 +442,7 @@ format_single_argument (SCM arg, int precision) LY_DEFINE (ly_format, "ly:format", 1, 0, 1, (SCM str, SCM rest), - "LilyPond specific format, supporting ~a ~[0-9]f.") + "LilyPond specific format, supporting @code{~a} and @code{~[0-9]f}.") { LY_ASSERT_TYPE (scm_is_string, str, 1); diff --git a/lily/global-context-scheme.cc b/lily/global-context-scheme.cc index 18d1d80712..8fbcc99b46 100644 --- a/lily/global-context-scheme.cc +++ b/lily/global-context-scheme.cc @@ -19,8 +19,9 @@ LY_DEFINE (ly_format_output, "ly:format-output", 1, 0, 0, (SCM context), - "Given a Global context in its final state, " - "process it and return the @code{Music_output} object in its final state.") + "Given a global context in its final state," + " process it and return the @code{Music_output} object" + " in its final state.") { Global_context *g = dynamic_cast (unsmob_context (context)); @@ -37,8 +38,8 @@ LY_DEFINE (ly_format_output, "ly:format-output", LY_DEFINE (ly_make_global_translator, "ly:make-global-translator", 1, 0, 0, (SCM global), - "Create a translator group and connect it to the global context\n" - "@var{global}. The translator group is returned.") + "Create a translator group and connect it to the global context" + " @var{global}. The translator group is returned.") { Global_context *g = dynamic_cast (unsmob_context (global)); LY_ASSERT_TYPE (unsmob_global_context, global, 1) @@ -52,10 +53,8 @@ LY_DEFINE (ly_make_global_translator, "ly:make-global-translator", LY_DEFINE (ly_make_global_context, "ly:make-global-context", 1, 0, 0, (SCM output_def), - "Set up a global interpretation context, using the output\n" - "block @var{output_def}.\n" - "The context is returned.\n" - ) + "Set up a global interpretation context, using the output" + " block @var{output_def}. The context is returned.\n") { LY_ASSERT_SMOB (Output_def, output_def, 1); Output_def *odef = unsmob_output_def (output_def); @@ -73,9 +72,8 @@ LY_DEFINE (ly_make_global_context, "ly:make-global-context", LY_DEFINE (ly_interpret_music_expression, "ly:interpret-music-expression", 2, 0, 0, (SCM mus, SCM ctx), - "Interpret the music expression @var{mus} in the\n" - "global context @var{ctx}. The context is returned in its\n" - "final state.\n") + "Interpret the music expression @var{mus} in the global context" + " @var{ctx}. The context is returned in its final state.") { LY_ASSERT_SMOB (Music, mus, 1); LY_ASSERT_TYPE (unsmob_global_context, ctx, 2); @@ -122,13 +120,13 @@ LY_DEFINE (ly_interpret_music_expression, "ly:interpret-music-expression", LY_DEFINE (ly_run_translator, "ly:run-translator", 2, 1, 0, (SCM mus, SCM output_def), - "Process @var{mus} according to @var{output_def}. \n" - "An interpretation context is set up,\n" - "and @var{mus} is interpreted with it. \n" - "The context is returned in its final state.\n" - "\n\n" - "Optionally, this routine takes an Object-key to\n" - "to uniquely identify the Score block containing it.\n") + "Process @var{mus} according to @var{output-def}. An" + " interpretation context is set up, and @var{mus} is" + " interpreted with it. The context is returned in its" + " final state.\n" + "\n" + "Optionally, this routine takes an object-key to" + " to uniquely identify the score block containing it.") { LY_ASSERT_SMOB (Music, mus, 1); LY_ASSERT_SMOB (Output_def, output_def, 2); diff --git a/lily/grob-array-scheme.cc b/lily/grob-array-scheme.cc index e01468f9f3..49fac4c21a 100644 --- a/lily/grob-array-scheme.cc +++ b/lily/grob-array-scheme.cc @@ -13,7 +13,7 @@ LY_DEFINE (ly_grob_array_length, "ly:grob-array-length", 1, 0, 0, (SCM grob_arr), - "Return the grob_array length.") + "Return the length of @var{grob-arr}.") { LY_ASSERT_SMOB (Grob_array, grob_arr, 1); @@ -25,7 +25,7 @@ LY_DEFINE (ly_grob_array_length, "ly:grob-array-length", LY_DEFINE (ly_grob_array_ref, "ly:grob-array-ref", 2, 0, 0, (SCM grob_arr, SCM index), - "Retrieve the @code{index} element of @code{grob-arr}.") + "Retrieve the @var{index}th element of @var{grob-arr}.") { Grob_array *me = unsmob_grob_array (grob_arr); LY_ASSERT_SMOB (Grob_array, grob_arr, 1); diff --git a/lily/grob-pq-engraver.cc b/lily/grob-pq-engraver.cc index 563e7218c0..7265d46347 100644 --- a/lily/grob-pq-engraver.cc +++ b/lily/grob-pq-engraver.cc @@ -49,7 +49,8 @@ Grob_pq_engraver::initialize () LY_DEFINE (ly_grob_pq_less_p, "ly:grob-pqalist", 1, 0, 0, (SCM mod), - "Dump the contents of module @var{mod} as an alist.") + "Dump the contents of module @var{mod} as an alist.") { SCM_VALIDATE_MODULE (1, mod); SCM obarr = SCM_MODULE_OBARRAY (mod); diff --git a/lily/module-scheme.cc b/lily/module-scheme.cc index ce08c42456..9f4832628f 100644 --- a/lily/module-scheme.cc +++ b/lily/module-scheme.cc @@ -30,7 +30,7 @@ module_define_closure_func (void *closure, SCM key, SCM val, SCM result) LY_DEFINE (ly_module_copy, "ly:module-copy", 2, 0, 0, (SCM dest, SCM src), - "Copy all bindings from module SRC into DEST.") + "Copy all bindings from module @var{src} into @var{dest}.") { #define FUNC_NAME __FUNCTION__ SCM_VALIDATE_MODULE (1, src); @@ -42,8 +42,8 @@ LY_DEFINE (ly_module_copy, "ly:module-copy", LY_DEFINE (ly_clear_anonymous_modules, "ly:clear-anonymous-modules", 0, 0, 0, (), - "Plug a GUILE 1.6 and 1.7 memory leak by breaking a weak reference " - "pointer cycle explicitly.") + "Plug a GUILE 1.6 and 1.7 memory leak by breaking a weak" + " reference pointer cycle explicitly.") { #ifdef MODULE_GC_KLUDGE clear_anonymous_modules (); @@ -68,9 +68,9 @@ ly_module_lookup (SCM module, SCM sym) LY_DEFINE (ly_modules_lookup, "ly:modules-lookup", 2, 1, 0, (SCM modules, SCM sym, SCM def), - "Lookup @var{sym} in the list @var{modules}, " - "returning the first occurence. " - "If not found, return @var{default}, or @code{#f}.") + "Look up @var{sym} in the list @var{modules}," + " returning the first occurence. If not found, return" + " @var{def} or @code{#f} if @var{def} isn't specified.") { for (SCM s = modules; scm_is_pair (s); s = scm_cdr (s)) { diff --git a/lily/moment-scheme.cc b/lily/moment-scheme.cc index 4eb3086adf..85155034c5 100644 --- a/lily/moment-scheme.cc +++ b/lily/moment-scheme.cc @@ -11,15 +11,13 @@ /* TODO: add optional factor argument. */ LY_DEFINE (ly_make_moment, "ly:make-moment", 2, 2, 0, (SCM n, SCM d, SCM gn, SCM gd), - "Create the rational number with main timing @var{n}/@var{d}, " - "and optional grace timin @var{gn}/@var{gd}.\n" + "Create the rational number with main timing @var{n}/@var{d}," + " and optional grace timing @var{gn}/@var{gd}.\n" "\n" - "\n" - "Moment is a point in musical time. " - "It is consists of a pair of rationals (@var{m}, @var{g}), " - "where @var{m} is the timing for the main\n" - "notes, and @var{g} the timing for grace notes. " - "In absence of grace notes, @var{g} is zero.\n") + "A @dfn{moment} is a point in musical time. It consists of" + " a pair of rationals (@var{m},@tie{}@var{g}), where @var{m} is" + " the timing for the main notes, and @var{g} the timing for" + " grace notes. In absence of grace notes, @var{g}@tie{}is zero.") { LY_ASSERT_TYPE (scm_is_integer, n, 1); LY_ASSERT_TYPE (scm_is_integer, d, 2); diff --git a/lily/music-function-scheme.cc b/lily/music-function-scheme.cc index 828929994a..c22634f152 100644 --- a/lily/music-function-scheme.cc +++ b/lily/music-function-scheme.cc @@ -2,14 +2,14 @@ LY_DEFINE (ly_music_function_p, "ly:music-function?", 1, 0, 0, (SCM x), - "Is @var{x} an @code{music-function}?") + "Is @var{x} a @code{music-function}?") { return is_music_function (x) ? SCM_BOOL_T : SCM_BOOL_F; } LY_DEFINE (ly_music_function_extract, "ly:music-function-extract", 1, 0, 0, (SCM x), - "Return the Scheme function inside @var{x}") + "Return the Scheme function inside@tie{}@var{x}.") { LY_ASSERT_TYPE (is_music_function, x, 1); @@ -18,10 +18,11 @@ LY_DEFINE (ly_music_function_extract, "ly:music-function-extract", 1, 0, 0, LY_DEFINE (ly_make_music_function, "ly:make-music-function", 2, 0, 0, (SCM signature, SCM func), - "Make a function to process music, to be used for the " - "parser. @code{func} is the function, and @code{signature} describes " - "Its arguments. @code{signature} is a list containing either " - "@code{ly:music?} predicates or other type predicates.") + "Make a function to process music, to be used for the" + " parser. @code{func} is the function, and @code{signature}" + " describes its arguments. @code{signature} is a list" + " containing either @code{ly:music?} predicates or other type" + " predicates.") { LY_ASSERT_TYPE (ly_is_procedure, func, 1); return make_music_function (signature, func); diff --git a/lily/music-scheme.cc b/lily/music-scheme.cc index c52b1d6a87..b6f0fbe7a2 100644 --- a/lily/music-scheme.cc +++ b/lily/music-scheme.cc @@ -13,7 +13,8 @@ LY_DEFINE (ly_music_length, "ly:music-length", 1, 0, 0, (SCM mus), - "Get the length of music expression @var{mus}, and return as a @code{Moment} object.") + "Get the length of music expression @var{mus} and return" + " it as a @code{Moment} object.") { LY_ASSERT_TYPE (unsmob_music, mus, 1); Music *sc = unsmob_music (mus); @@ -22,8 +23,8 @@ LY_DEFINE (ly_music_length, "ly:music-length", LY_DEFINE (ly_music_property, "ly:music-property", 2, 1, 0, (SCM mus, SCM sym, SCM dfault), - "Get the property @var{sym} of music expression @var{mus}.\n" - "If @var{sym} is undefined, return @code{'()}.\n") + "Get the property @var{sym} of music expression @var{mus}." + " If @var{sym} is undefined, return @code{'()}.") { LY_ASSERT_TYPE (unsmob_music, mus, 1); return ly_prob_property (mus, sym, dfault); @@ -31,7 +32,8 @@ LY_DEFINE (ly_music_property, LY_DEFINE (ly_music_set_property_x, "ly:music-set-property!", 3, 0, 0, (SCM mus, SCM sym, SCM val), - "Set property @var{sym} in music expression @var{mus} to @var{val}.") + "Set property @var{sym} in music expression @var{mus} to" + " @var{val}.") { LY_ASSERT_TYPE (unsmob_music, mus, 1); @@ -42,12 +44,12 @@ LY_DEFINE (ly_music_set_property_x, "ly:music-set-property!", /* todo: property args */ LY_DEFINE (ly_make_music, "ly:make-music", 1, 0, 0, (SCM props), - "Make a C++ Music object, initialize with\n" - "@var{props}. \n\n" - "" - "This function is for internal use, and is only called by " - "@code{make-music}, which is the preferred interface " - "for creating music objects. ") + "Make a C++ @code{Music} object and initialize it with" + " @var{props}.\n" + "\n" + "This function is for internal use and is only called by" + " @code{make-music}, which is the preferred interface" + " for creating music objects.") { Music *ms = new Music (props); return ms->unprotect (); @@ -55,7 +57,7 @@ LY_DEFINE (ly_make_music, "ly:make-music", LY_DEFINE (ly_music_p, "ly:music?", 1, 0, 0, (SCM obj), - "Type predicate") + "Type predicate.") { return scm_from_bool (unsmob_music (obj)); } @@ -63,10 +65,9 @@ LY_DEFINE (ly_music_p, "ly:music?", /* todo: property args */ LY_DEFINE (ly_music_mutable_properties, "ly:music-mutable-properties", 1, 0, 0, (SCM mus), - "Return an alist containing the mutable properties of @var{mus}.\n" - "The immutable properties are not available, since " - "they are constant and initialized by the " - "@code{make-music} function.\n") + "Return an alist containing the mutable properties of @var{mus}." + " The immutable properties are not available, since they are" + " constant and initialized by the @code{make-music} function.") { LY_ASSERT_TYPE (unsmob_music, mus, 1); Music *m = unsmob_music (mus); @@ -75,8 +76,8 @@ LY_DEFINE (ly_music_mutable_properties, "ly:music-mutable-properties", LY_DEFINE (ly_music_list_p, "ly:music-list?", 1, 0, 0, (SCM lst), - "Type predicate: return true if @var{lst} is a list " - "of music objects.") + "Type predicate: Return true if @var{lst} is a list" + " of music objects.") { if (scm_list_p (lst) == SCM_BOOL_T) while (scm_is_pair (lst)) @@ -91,7 +92,7 @@ LY_DEFINE (ly_music_list_p, "ly:music-list?", LY_DEFINE (ly_music_deep_copy, "ly:music-deep-copy", 1, 0, 0, (SCM m), - "Copy @var{m} and all sub expressions of @var{m}") + "Copy @var{m} and all sub expressions of@tie{}@var{m}.") { SCM copy = m; if (unsmob_music (m)) @@ -107,8 +108,8 @@ LY_DEFINE (ly_music_deep_copy, "ly:music-deep-copy", LY_DEFINE (ly_music_transpose, "ly:music-transpose", 2, 0, 0, (SCM m, SCM p), - "Transpose @var{m} such that central C is mapped to @var{p}. " - "Return @var{m}.") + "Transpose @var{m} such that central@tie{}C is mapped" + " to@tie{}@var{p}. Return@tie{}@var{m}.") { LY_ASSERT_TYPE (unsmob_music, m, 1); LY_ASSERT_SMOB (Pitch, p, 2); @@ -126,7 +127,7 @@ LY_DEFINE (ly_music_transpose, "ly:music-transpose", */ LY_DEFINE (ly_music_compress, "ly:music-compress", 2, 0, 0, (SCM m, SCM factor), - "Compress music object @var{m} by moment @var{factor}.") + "Compress music object@tie{}@var{m} by moment @var{factor}.") { LY_ASSERT_TYPE (unsmob_music, m, 1); LY_ASSERT_TYPE (unsmob_moment, factor, 2); @@ -138,7 +139,8 @@ LY_DEFINE (ly_music_compress, "ly:music-compress", LY_DEFINE (ly_music_duration_length, "ly:music-duration-length", 1, 0, 0, (SCM mus), - "Extract the duration field from @var{mus}, and return the length.") + "Extract the duration field from @var{mus} and return the" + " length.") { LY_ASSERT_TYPE (unsmob_music, mus, 1); Music *m = unsmob_music (mus); @@ -155,7 +157,8 @@ LY_DEFINE (ly_music_duration_length, "ly:music-duration-length", 1, 0, 0, LY_DEFINE (ly_music_duration_compress, "ly:music-duration-compress", 2, 0, 0, (SCM mus, SCM fact), - "Compress @var{mus} by factor @var{fact}, which is a @code{Moment}.") + "Compress @var{mus} by factor @var{fact}, which is a" + " @code{Moment}.") { LY_ASSERT_TYPE (unsmob_music, mus, 1); LY_ASSERT_SMOB (Moment, fact, 2); @@ -178,7 +181,8 @@ LY_DEFINE (ly_music_duration_compress, "ly:music-duration-compress", 2, 0, 0, */ LY_DEFINE (ly_transpose_key_alist, "ly:transpose-key-alist", 2, 0, 0, (SCM l, SCM pit), - "Make a new key alist of @var{l} transposed by pitch @var{pit}") + "Make a new key alist of@tie{}@var{l} transposed by" + " pitch @var{pit}.") { SCM newlist = SCM_EOL; Pitch *p = unsmob_pitch (pit); diff --git a/lily/note-head-scheme.cc b/lily/note-head-scheme.cc index 89f17453cf..bf0bd99177 100644 --- a/lily/note-head-scheme.cc +++ b/lily/note-head-scheme.cc @@ -13,8 +13,8 @@ LY_DEFINE (ly_note_head__stem_attachment, "ly:note-head::stem-attachment", 2, 0, 0, (SCM font_metric, SCM glyph_name), - "Get attachment in @var{font-metric} for attaching a stem to notehead " - "@var{glyph-name}.") + "Get attachment in @var{font-metric} for attaching a stem to" + " notehead @var{glyph-name}.") { LY_ASSERT_SMOB (Font_metric, font_metric, 1); Font_metric *fm = unsmob_metrics (font_metric); diff --git a/lily/open-type-font-scheme.cc b/lily/open-type-font-scheme.cc index 6f95641325..173eb56d37 100644 --- a/lily/open-type-font-scheme.cc +++ b/lily/open-type-font-scheme.cc @@ -11,8 +11,8 @@ LY_DEFINE (ly_font_sub_fonts, "ly:font-sub-fonts", 1, 0, 0, (SCM font), - "Given the font metric @var{font} of an OpenType font, return the " - "names of the subfonts within @var{font}.") + "Given the font metric @var{font} of an OpenType font, return the" + " names of the subfonts within @var{font}.") { LY_ASSERT_SMOB (Font_metric, font, 1); Font_metric *fm = unsmob_metrics (font); @@ -21,8 +21,8 @@ LY_DEFINE (ly_font_sub_fonts, "ly:font-sub-fonts", 1, 0, 0, LY_DEFINE (ly_otf_font_glyph_info, "ly:otf-font-glyph-info", 2, 0, 0, (SCM font, SCM glyph), - "Given the font metric @var{font} of an OpenType font, return the " - "information about named glyph @var{glyph} (a string)") + "Given the font metric @var{font} of an OpenType font, return the" + " information about named glyph @var{glyph} (a string).") { Modified_font_metric *fm = dynamic_cast (unsmob_metrics (font)); @@ -37,8 +37,8 @@ LY_DEFINE (ly_otf_font_glyph_info, "ly:otf-font-glyph-info", 2, 0, 0, LY_DEFINE (ly_otf_font_table_data, "ly:otf-font-table-data", 2, 0, 0, (SCM font, SCM tag), - "Extract a table @var{tag} from @var{font}. Return empty string for " - "non-existent @var{tag}.") + "Extract a table @var{tag} from @var{font}. Return empty string" + " for non-existent @var{tag}.") { Modified_font_metric *fm = dynamic_cast (unsmob_metrics (font)); @@ -74,7 +74,7 @@ LY_DEFINE (ly_otf_font_p, "ly:otf-font?", 1, 0, 0, LY_DEFINE (ly_otf_glyph_list, "ly:otf-glyph-list", 1, 0, 0, (SCM font), - "Return a list of glyphnames for @var{font}.") + "Return a list of glyph names for @var{font}.") { Modified_font_metric *fm = dynamic_cast (unsmob_metrics (font)); diff --git a/lily/output-def-scheme.cc b/lily/output-def-scheme.cc index ea216a371f..29c8949ab9 100644 --- a/lily/output-def-scheme.cc +++ b/lily/output-def-scheme.cc @@ -16,8 +16,9 @@ LY_DEFINE (ly_output_def_lookup, "ly:output-def-lookup", 2, 1, 0, (SCM pap, SCM sym, SCM def), - "Lookup @var{sym} in the Output_def @var{pap}. " - "Return the value or @var{def} (which defaults to @code{'()}) if undefined.") + "Look up @var{sym} in the @var{pap} output definition" + " (e.g., @code{\\paper}). Return the value or @var{def}" + " (which defaults to @code{'()}) if undefined.") { LY_ASSERT_SMOB (Output_def, pap, 1); Output_def *op = unsmob_output_def (pap); @@ -46,7 +47,7 @@ LY_DEFINE (ly_output_def_scope, "ly:output-def-scope", LY_DEFINE (ly_output_def_parent, "ly:output-def-parent", 1, 0, 0, (SCM def), - "Get the parent output-def of @var{def}.") + "Get the parent output definition of @var{def}.") { LY_ASSERT_SMOB (Output_def, def, 1); Output_def *op = unsmob_output_def (def); @@ -55,7 +56,7 @@ LY_DEFINE (ly_output_def_parent, "ly:output-def-parent", LY_DEFINE (ly_output_def_clone, "ly:output-def-clone", 1, 0, 0, (SCM def), - "Clone @var{def}.") + "Clone output definition @var{def}.") { LY_ASSERT_SMOB (Output_def, def, 1); Output_def *op = unsmob_output_def (def); @@ -91,7 +92,7 @@ LY_DEFINE (ly_output_def_p, "ly:output-def?", LY_DEFINE (ly_paper_outputscale, "ly:paper-outputscale", 1, 0, 0, (SCM bp), - "Get output-scale for BP.") + "Get output-scale for @var{bp}.") { LY_ASSERT_SMOB (Output_def, bp, 1); Output_def *b = unsmob_output_def (bp); @@ -100,7 +101,7 @@ LY_DEFINE (ly_paper_outputscale, "ly:paper-outputscale", LY_DEFINE (ly_make_output_def, "ly:make-output-def", 0, 0, 0, (), - "Make a output def.") + "Make an output definition.") { Output_def *bp = new Output_def; return bp->unprotect (); @@ -108,11 +109,9 @@ LY_DEFINE (ly_make_output_def, "ly:make-output-def", LY_DEFINE (ly_paper_get_font, "ly:paper-get-font", 2, 0, 0, (SCM paper_smob, SCM chain), - - "Return a font metric satisfying the font-qualifiers " - "in the alist chain @var{chain}.\n" - "(An alist chain is a list of alists, " - "containing grob properties).\n") + "Return a font metric satisfying the font-qualifiers" + " in the alist chain @var{chain}. (An alist chain is a" + " list of alists, containing grob properties.)") { LY_ASSERT_SMOB (Output_def, paper_smob, 1); diff --git a/lily/page-breaking-scheme.cc b/lily/page-breaking-scheme.cc index 87d21383b3..2241b503a7 100644 --- a/lily/page-breaking-scheme.cc +++ b/lily/page-breaking-scheme.cc @@ -13,8 +13,9 @@ LY_DEFINE (ly_page_turn_breaking, "ly:page-turn-breaking", 1, 0, 0, (SCM pb), - "Optimally break (pages and lines) the Paper_book PB such that page turns " - "only happen in specified places, returning its pages.") + "Optimally break (pages and lines) the @code{Paper_book} object" + " @var{pb} such that page turns only happen in specified places," + " returning its pages.") { Page_turn_page_breaking b (unsmob_paper_book (pb)); return b.solve (); @@ -22,8 +23,9 @@ LY_DEFINE (ly_page_turn_breaking, "ly:page-turn-breaking", LY_DEFINE (ly_optimal_breaking, "ly:optimal-breaking", 1, 0, 0, (SCM pb), - "Optimally break (pages and lines) the Paper_book PB to minimise badness in " - "bother vertical and horizontal spacing.") + "Optimally break (pages and lines) the @code{Paper_book} object" + " @var{pb} to minimize badness in bother vertical and horizontal" + " spacing.") { Optimal_page_breaking b (unsmob_paper_book (pb)); return b.solve (); diff --git a/lily/pango-font-scheme.cc b/lily/pango-font-scheme.cc index fe6d4bacd4..20f15764b5 100644 --- a/lily/pango-font-scheme.cc +++ b/lily/pango-font-scheme.cc @@ -30,7 +30,7 @@ LY_DEFINE (ly_pango_font_p, "ly:pango-font?", LY_DEFINE (ly_pango_font_physical_fonts, "ly:pango-font-physical-fonts", 1, 0, 0, (SCM f), - "Return alist of (PSNAME . FILENAME) tuples.") + "Return alist of @code{(PSNAME . FILENAME)} tuples.") { Pango_font *pf = dynamic_cast (unsmob_metrics (f)); diff --git a/lily/pango-select-scheme.cc b/lily/pango-select-scheme.cc index 613cd01cae..6c8bcd42cd 100644 --- a/lily/pango-select-scheme.cc +++ b/lily/pango-select-scheme.cc @@ -13,7 +13,8 @@ LY_DEFINE (ly_make_pango_description_string, "ly:make-pango-description-string", 2, 0, 0, (SCM chain, SCM size), - "Make a PangoFontDescription string for the property alist @var{chain} at size @var{size}.") + "Make a @code{PangoFontDescription} string for the property" + " alist @var{chain} at size @var{size}.") { LY_ASSERT_TYPE (scm_is_number, size, 1); PangoFontDescription *pfd = properties_to_pango_description (chain, scm_to_double (size)); diff --git a/lily/paper-book-scheme.cc b/lily/paper-book-scheme.cc index 94bb17f05e..275e3ced53 100644 --- a/lily/paper-book-scheme.cc +++ b/lily/paper-book-scheme.cc @@ -12,7 +12,7 @@ LY_DEFINE (ly_paper_book_pages, "ly:paper-book-pages", 1, 0, 0, (SCM pb), - "Return pages in book PB.") + "Return pages in book @var{pb}.") { LY_ASSERT_SMOB (Paper_book, pb, 1); return unsmob_paper_book (pb)->pages (); @@ -42,7 +42,7 @@ LY_DEFINE (ly_paper_book_performances, "ly:paper-book-performances", LY_DEFINE (ly_paper_book_systems, "ly:paper-book-systems", 1, 0, 0, (SCM pb), - "Return systems in book PB.") + "Return systems in book @var{pb}.") { LY_ASSERT_SMOB (Paper_book, pb, 1); return unsmob_paper_book (pb)->systems (); @@ -50,7 +50,7 @@ LY_DEFINE (ly_paper_book_systems, "ly:paper-book-systems", LY_DEFINE (ly_paper_book_paper, "ly:paper-book-paper", 1, 0, 0, (SCM pb), - "Return pages in book PB.") + "Return pages in book @var{pb}.") { LY_ASSERT_SMOB (Paper_book, pb, 1); Paper_book *pbook = unsmob_paper_book (pb); diff --git a/lily/paper-outputter-scheme.cc b/lily/paper-outputter-scheme.cc index 2149f0ec2c..625494d6d9 100644 --- a/lily/paper-outputter-scheme.cc +++ b/lily/paper-outputter-scheme.cc @@ -14,8 +14,8 @@ LY_DEFINE (ly_make_paper_outputter, "ly:make-paper-outputter", 2, 0, 0, (SCM port, SCM format), - "Create an outputter that evaluates within " - "@code{output-}@var{format}, writing to @var{port}.") + "Create an outputter that evaluates within" + " @code{output-}@var{format}, writing to @var{port}.") { LY_ASSERT_TYPE (ly_is_port, port, 1); LY_ASSERT_TYPE (ly_is_symbol, format, 2); diff --git a/lily/paper-score-scheme.cc b/lily/paper-score-scheme.cc index 055b5363df..b973647fa2 100644 --- a/lily/paper-score-scheme.cc +++ b/lily/paper-score-scheme.cc @@ -11,7 +11,8 @@ LY_DEFINE (ly_paper_score_paper_systems, "ly:paper-score-paper-systems", 1, 0, 0, (SCM paper_score), - "Return vector of paper_system objects from @var{paper-score}.") + "Return vector of @code{paper_system} objects from" + " @var{paper-score}.") { LY_ASSERT_TYPE (unsmob_paper_score, paper_score, 1); diff --git a/lily/performance-scheme.cc b/lily/performance-scheme.cc index c16c0c3754..a00e6b8efd 100644 --- a/lily/performance-scheme.cc +++ b/lily/performance-scheme.cc @@ -10,7 +10,7 @@ LY_DEFINE (ly_performance_write, "ly:performance-write", 2, 0, 0, (SCM performance, SCM filename), - "Write @var{performance} to @var{filename}") + "Write @var{performance} to @var{filename}.") { LY_ASSERT_TYPE (unsmob_performance, performance, 1); LY_ASSERT_TYPE (scm_is_string, filename, 2); diff --git a/lily/pfb-scheme.cc b/lily/pfb-scheme.cc index f22a745ac7..7fcdc73de5 100644 --- a/lily/pfb-scheme.cc +++ b/lily/pfb-scheme.cc @@ -31,8 +31,8 @@ LY_DEFINE (ly_pfb_2_pfa, "ly:pfb->pfa", LY_DEFINE (ly_otf_2_cff, "ly:otf->cff", 1, 0, 0, (SCM otf_file_name), - "Convert the contents of a OTF file to CFF file, returning it as " - " a string.") + "Convert the contents of an OTF file to a CFF file," + " returning it as a string.") { LY_ASSERT_TYPE (scm_is_string, otf_file_name, 1); diff --git a/lily/pitch-scheme.cc b/lily/pitch-scheme.cc index e2f3aecf69..12ddddf10a 100644 --- a/lily/pitch-scheme.cc +++ b/lily/pitch-scheme.cc @@ -10,8 +10,8 @@ LY_DEFINE (ly_pitch_transpose, "ly:pitch-transpose", 2, 0, 0, (SCM p, SCM delta), - "Transpose @var{p} by the amount @var{delta}, " - "where @var{delta} is relative to middle C.") + "Transpose @var{p} by the amount @var{delta}," + " where @var{delta} is relative to middle@tie{}C.") { LY_ASSERT_SMOB (Pitch, p, 1); LY_ASSERT_SMOB (Pitch, delta, 2); @@ -24,11 +24,11 @@ LY_DEFINE (ly_pitch_transpose, "ly:pitch-transpose", /* Should add optional args. */ LY_DEFINE (ly_make_pitch, "ly:make-pitch", 2, 1, 0, (SCM octave, SCM note, SCM alter), - "@var{octave} is specified by an integer, " - "zero for the octave containing middle C. " - "@var{note} is a number from 0 to 6, " - "with 0 corresponding to C and 6 corresponding to B. " - "The @var{alter} is a rational number of whole tones for alteration.") + "@var{octave} is specified by an integer, zero for the octave" + " containing middle@tie{}C. @var{note} is a number from 0" + " to@tie{}6, with 0 corresponding to pitch@tie{}C and 6" + " corresponding to pitch@tie{}B. @var{alter} is a rational" + " number of whole tones for alteration.") { LY_ASSERT_TYPE (scm_is_integer, octave, 1); LY_ASSERT_TYPE (scm_is_integer, note, 2); @@ -51,7 +51,8 @@ LY_DEFINE (ly_pitch_negate, "ly:pitch-negate", 1, 0, 0, LY_DEFINE (ly_pitch_steps, "ly:pitch-steps", 1, 0, 0, (SCM p), - "Number of steps counted from middle C of the pitch @var{p}.") + "Number of steps counted from middle@tie{}C of the" + " pitch@tie{}@var{p}.") { LY_ASSERT_SMOB (Pitch, p, 1); Pitch *pp = unsmob_pitch (p); @@ -60,7 +61,7 @@ LY_DEFINE (ly_pitch_steps, "ly:pitch-steps", 1, 0, 0, LY_DEFINE (ly_pitch_octave, "ly:pitch-octave", 1, 0, 0, (SCM pp), - "Extract the octave from pitch @var{p}.") + "Extract the octave from pitch@tie{}@var{pp}.") { LY_ASSERT_SMOB (Pitch, pp, 1); Pitch *p = unsmob_pitch (pp); @@ -70,7 +71,7 @@ LY_DEFINE (ly_pitch_octave, "ly:pitch-octave", LY_DEFINE (ly_pitch_alteration, "ly:pitch-alteration", 1, 0, 0, (SCM pp), - "Extract the alteration from pitch @var{p}.") + "Extract the alteration from pitch@tie{}@var{pp}.") { LY_ASSERT_SMOB (Pitch, pp, 1); Pitch *p = unsmob_pitch (pp); @@ -81,7 +82,7 @@ LY_DEFINE (ly_pitch_alteration, "ly:pitch-alteration", LY_DEFINE (pitch_notename, "ly:pitch-notename", 1, 0, 0, (SCM pp), - "Extract the note name from pitch @var{pp}.") + "Extract the note name from pitch @var{pp}.") { LY_ASSERT_SMOB (Pitch, pp, 1); Pitch *p = unsmob_pitch (pp); @@ -91,7 +92,8 @@ LY_DEFINE (pitch_notename, "ly:pitch-notename", LY_DEFINE (ly_pitch_quartertones, "ly:pitch-quartertones", 1, 0, 0, (SCM pp), - "Calculate the number of quarter tones of @var{p} from middle C.") + "Calculate the number of quarter tones of@tie{}@var{pp} from" + " middle@tie{}C.") { LY_ASSERT_SMOB (Pitch, pp, 1); Pitch *p = unsmob_pitch (pp); @@ -101,7 +103,8 @@ LY_DEFINE (ly_pitch_quartertones, "ly:pitch-quartertones", LY_DEFINE (ly_pitch_semitones, "ly:pitch-semitones", 1, 0, 0, (SCM pp), - "calculate the number of semitones of @var{p} from middle C.") + "Calculate the number of semitones of@tie{}@var{pp} from" + " middle@tie{}C.") { LY_ASSERT_SMOB (Pitch, pp, 1); Pitch *p = unsmob_pitch (pp); @@ -127,8 +130,8 @@ LY_DEFINE (ly_pitch_less_p, "ly:pitchtype () == type); @@ -61,7 +61,7 @@ LY_DEFINE (ly_prob_type_p, "ly:prob-type?", LY_DEFINE (ly_make_prob, "ly:make-prob", 2, 0, 1, (SCM type, SCM init, SCM rest), - "Create a Prob.") + "Create a @code{Prob} object.") { Prob *pr = new Prob (type, init); @@ -87,9 +87,9 @@ LY_DEFINE (ly_paper_system_p, "ly:paper-system?", LY_DEFINE (ly_paper_system_minimum_distance, "ly:paper-system-minimum-distance", 2, 0, 0, (SCM sys1, SCM sys2), - "Measure the minimum distance between these two paper-systems " - "using their stored skylines if possible and falling back to " - "their extents otherwise.") + "Measure the minimum distance between these two paper-systems," + " using their stored skylines if possible and falling back to" + " their extents otherwise.") { Real ret = 0; Prob *p1 = unsmob_prob (sys1); diff --git a/lily/profile.cc b/lily/profile.cc index 0390a64a62..234780c2ec 100644 --- a/lily/profile.cc +++ b/lily/profile.cc @@ -16,8 +16,9 @@ SCM prob_property_lookup_table; LY_DEFINE (ly_property_lookup_stats, "ly:property-lookup-stats", 1, 0, 0, (SCM sym), - "Return hash table with a property access corresponding to @var{sym}. " - "Choices are prob, grob and context.") + "Return hash table with a property access corresponding to" + " @var{sym}. Choices are @code{prob}, @code{grob}, and" + " @code{context}.") { if (sym == ly_symbol2scm ("context")) return context_property_lookup_table ? context_property_lookup_table diff --git a/lily/program-option-scheme.cc b/lily/program-option-scheme.cc index 638aaf634d..4ec898092e 100644 --- a/lily/program-option-scheme.cc +++ b/lily/program-option-scheme.cc @@ -168,7 +168,7 @@ get_help_string () LY_DEFINE (ly_option_usage, "ly:option-usage", 0, 0, 0, (), - "Print @code{ly:set-option} usage") + "Print @code{ly:set-option} usage.") { string help = get_help_string (); progress_indication (help); @@ -219,19 +219,19 @@ LY_DEFINE (ly_set_option, "ly:set-option", 1, 1, 0, (SCM var, SCM val), } LY_DEFINE (ly_command_line_options, "ly:command-line-options", 0, 0, 0, (), - "The Scheme specified on command-line with @samp{-d}.") + "The Scheme options specified on command-line with @option{-d}.") { return ly_string2scm (init_scheme_variables_global); } LY_DEFINE (ly_command_line_code, "ly:command-line-code", 0, 0, 0, (), - "The Scheme specified on command-line with @samp{-e}.") + "The Scheme code specified on command-line with @option{-e}.") { return ly_string2scm (init_scheme_code_global); } LY_DEFINE (ly_command_line_verbose_p, "ly:command-line-verbose?", 0, 0, 0, (), - "Was be_verbose_global set?") + "Was @code{be_verbose_global} set?") { return scm_from_bool (be_verbose_global); } diff --git a/lily/scale.cc b/lily/scale.cc index ecd2b9357e..5d8ccc9a38 100644 --- a/lily/scale.cc +++ b/lily/scale.cc @@ -17,7 +17,7 @@ */ LY_DEFINE (ly_make_scale, "ly:make-scale", 1, 0, 0, (SCM steps), - "Create a scale. Takes a vector of ints as argument") + "Create a scale. Takes a vector of integers as argument.") { bool type_ok = scm_is_vector (steps); diff --git a/lily/scheme-listener-scheme.cc b/lily/scheme-listener-scheme.cc index 004c14c14f..01eaa22ba1 100644 --- a/lily/scheme-listener-scheme.cc +++ b/lily/scheme-listener-scheme.cc @@ -10,11 +10,10 @@ LY_DEFINE (ly_make_listener, "ly:make-listener", 1, 0, 0, (SCM callback), - "Creates a listener. Any time the listener hears\n" - " an object, it will call @var{callback}\n" - " with that object.\n" + "Create a listener. Any time the listener hears an object," + " it will call @var{callback} with that object.\n" "\n" - " @var{callback} should take exactly one argument." ) + "@var{callback} should take exactly one argument.") { LY_ASSERT_TYPE (ly_is_procedure, callback, 1); Scheme_listener *l = new Scheme_listener (callback); diff --git a/lily/score-scheme.cc b/lily/score-scheme.cc index 83111f6707..c103475302 100644 --- a/lily/score-scheme.cc +++ b/lily/score-scheme.cc @@ -30,7 +30,7 @@ LY_DEFINE (ly_make_score, "ly:make-score", LY_DEFINE (ly_score_output_defs, "ly:score-output-defs", 1, 0, 0, (SCM score), - "All output defs in a score.") + "All output definitions in a score.") { LY_ASSERT_SMOB (Score, score, 1); Score *sc = unsmob_score (score); @@ -45,7 +45,7 @@ LY_DEFINE (ly_score_output_defs, "ly:score-output-defs", LY_DEFINE (ly_score_header, "ly:score-header", 1, 0, 0, (SCM score), - "return score header.") + "Return score header.") { LY_ASSERT_SMOB (Score, score, 1); Score *sc = unsmob_score (score); @@ -55,7 +55,7 @@ LY_DEFINE (ly_score_header, "ly:score-header", LY_DEFINE (ly_score_music, "ly:score-music", 1, 0, 0, (SCM score), - "return score music.") + "Return score music.") { LY_ASSERT_SMOB (Score, score, 1); Score *sc = unsmob_score (score); @@ -73,10 +73,10 @@ LY_DEFINE (ly_score_error_p, "ly:score-error?", LY_DEFINE (ly_score_embedded_format, "ly:score-embedded-format", 2, 0, 0, (SCM score, SCM layout), - "Run @var{score} through @var{layout}, an output definition, " - "scaled to correct output-scale already, " - "return a list of layout-lines. " - "\nTake optional Object_key argument.") + "Run @var{score} through @var{layout} (an output definition)" + " scaled to correct output-scale already, returning a list of" + " layout-lines. This function takes an optional" + " @code{Object_key} argument.") { LY_ASSERT_SMOB (Score, score, 1); LY_ASSERT_SMOB (Output_def, layout, 2); diff --git a/lily/script-column.cc b/lily/script-column.cc index 1ae7969b4e..3e4092f7c6 100644 --- a/lily/script-column.cc +++ b/lily/script-column.cc @@ -32,7 +32,7 @@ Script_column::add_side_positioned (Grob *me, Grob *script) LY_DEFINE (ly_grob_script_priority_less, "ly:grob-script-priority-less", 2, 0, 0, (SCM a, SCM b), - "Compare two grobs by script priority. For internal use.") + "Compare two grobs by script priority. For internal use.") { Grob *i1 = unsmob_grob (a); Grob *i2 = unsmob_grob (b); diff --git a/lily/simple-closure.cc b/lily/simple-closure.cc index 22ee294f49..737bb3965b 100644 --- a/lily/simple-closure.cc +++ b/lily/simple-closure.cc @@ -92,9 +92,10 @@ LY_DEFINE (ly_simple_closure_p, "ly:simple-closure?", LY_DEFINE (ly_make_simple_closure, "ly:make-simple-closure", 1, 0, 0, (SCM expr), - "Make a simple closure. @var{expr} should be form of " - "@code{(@var{func} @var{a1} @var{A2} ...)}, and will be invoked " - "as @code{(@var{func} @var{delayed-arg} @var{a1} @var{a2} ... )}.") + "Make a simple closure. @var{expr} should be form of" + " @code{(@var{func} @var{a1} @var{A2} @dots{})}, and will be" + " invoked as @code{(@var{func} @var{delayed-arg} @var{a1}" + " @var{a2} @dots{})}.") { SCM z; @@ -104,9 +105,9 @@ LY_DEFINE (ly_make_simple_closure, "ly:make-simple-closure", LY_DEFINE (ly_eval_simple_closure, "ly:eval-simple-closure", 2, 2, 0, (SCM delayed, SCM closure, SCM scm_start, SCM scm_end), - "Evaluate a simple closure with the given delayed argument. " - "If start and end are defined, evaluate it purely with those " - "start- and end-points.") + "Evaluate a simple @var{closure} with the given @var{delayed}" + " argument. If @var{scm-start} and @var{scm-end} are defined," + " evaluate it purely with those start and end points.") { bool pure = (scm_is_number (scm_start) && scm_is_number (scm_end)); int start = robust_scm2int (scm_start, 0); diff --git a/lily/simple-spacer-scheme.cc b/lily/simple-spacer-scheme.cc index db326704fc..fda38ab503 100644 --- a/lily/simple-spacer-scheme.cc +++ b/lily/simple-spacer-scheme.cc @@ -15,13 +15,19 @@ LY_DEFINE (ly_solve_spring_rod_problem, "ly:solve-spring-rod-problem", 4, 1, 0, (SCM springs, SCM rods, SCM length, SCM ragged), - "Solve a spring and rod problem for @var{count} objects, that " - "are connected by @var{count-1} springs, and an arbitrary number of rods " - "Springs have the format (ideal, inverse_hooke) and rods (idx1, idx2, distance) " - "@var{length} is a number, @var{ragged} a boolean " - "Return: a list containing the force (positive for stretching, " - "negative for compressing and #f for non-satisfied constraints) " - "followed by the @var{spring-count}+1 positions of the objects. ") + "Solve a spring and rod problem for @var{count} objects, that" + " are connected by @var{count}-1 @var{springs}, and an arbitrary" + " number of @var{rods}. @var{count} is implicitly given by" + " @var{springs} and @var{rods}. The @var{springs} argument has" + " the format @code{(ideal, inverse_hook)} and @var{rods} is of" + " the form @code{(idx1, idx2, distance)}.\n" + "\n" + "@var{length} is a number, @var{ragged} a boolean.\n" + "\n" + "The function returns a list containing the force (positive for" + " stretching, negative for compressing and @code{#f} for" + " non-satisfied constraints) followed by @var{spring-count}+1" + " positions of the objects.") { int len = scm_ilength (springs); if (len == 0) diff --git a/lily/smobs.cc b/lily/smobs.cc index a4c88fe58b..7bdaaa7f92 100644 --- a/lily/smobs.cc +++ b/lily/smobs.cc @@ -23,7 +23,7 @@ ADD_SCM_INIT_FUNC (init_smob_protection, init_smob_protection); LY_DEFINE (ly_smob_protects, "ly:smob-protects", 0, 0, 0, (), - "Return lily's internal smob protection list") + "Return LilyPond's internal smob protection list.") { return scm_is_pair (smob_protection_list) ? scm_cdr (smob_protection_list) diff --git a/lily/spanner-scheme.cc b/lily/spanner-scheme.cc index 0dc62b3a51..3e9e947060 100644 --- a/lily/spanner-scheme.cc +++ b/lily/spanner-scheme.cc @@ -12,8 +12,8 @@ LY_DEFINE (ly_spanner_bound, "ly:spanner-bound", 2, 0, 0, (SCM slur, SCM dir), - "Get one of the bounds of @var{spanner}. @var{dir} is @code{-1} " - "for left, and @code{1} for right.") + "Get one of the bounds of @var{slur}. @var{dir} is @code{-1}" + " for left, and @code{1} for right.") { LY_ASSERT_TYPE (unsmob_spanner, slur, 1); LY_ASSERT_TYPE (is_direction, dir,2); @@ -38,7 +38,7 @@ LY_DEFINE (ly_spanner_broken_into, "ly:spanner-broken-into", LY_DEFINE (ly_spanner_p, "ly:spanner?", 1, 0, 0, (SCM g), - "Is @var{g} a spanner object?") + "Is @var{g} a spanner object?") { Grob *me = unsmob_grob (g); bool b = dynamic_cast (me); diff --git a/lily/stencil-scheme.cc b/lily/stencil-scheme.cc index 125b142d26..a092856a0a 100644 --- a/lily/stencil-scheme.cc +++ b/lily/stencil-scheme.cc @@ -18,7 +18,8 @@ LY_DEFINE (ly_stencil_translate_axis, "ly:stencil-translate-axis", 3, 0, 0, (SCM stil, SCM amount, SCM axis), - "Return a copy of @var{stil} but translated by @var{amount} in @var{axis} direction.") + "Return a copy of @var{stil} but translated by @var{amount}" + " in @var{axis} direction.") { Stencil *s = unsmob_stencil (stil); LY_ASSERT_SMOB (Stencil, stil, 1); @@ -35,8 +36,8 @@ LY_DEFINE (ly_stencil_translate_axis, "ly:stencil-translate-axis", LY_DEFINE (ly_stencil_translate, "ly:stencil-translate", 2, 0, 0, (SCM stil, SCM offset), - "Return a @var{stil}, " - "but translated by @var{offset} (a pair of numbers).") + "Return a @var{stil}, but translated by @var{offset}" + " (a pair of numbers).") { Stencil *s = unsmob_stencil (stil); LY_ASSERT_SMOB (Stencil, stil, 1); @@ -60,8 +61,9 @@ LY_DEFINE (ly_stencil_expr, "ly:stencil-expr", LY_DEFINE (ly_stencil_extent, "ly:stencil-extent", 2, 0, 0, (SCM stil, SCM axis), - "Return a pair of numbers signifying the extent of @var{stil} in " - "@var{axis} direction (0 or 1 for x and y axis respectively).") + "Return a pair of numbers signifying the extent of @var{stil} in" + " @var{axis} direction (@code{0} or @code{1} for x and" + " y@tie{}axis, respectively).") { Stencil *s = unsmob_stencil (stil); LY_ASSERT_SMOB (Stencil, stil, 1); @@ -72,7 +74,7 @@ LY_DEFINE (ly_stencil_extent, "ly:stencil-extent", LY_DEFINE (ly_stencil_empty_p, "ly:stencil-empty?", 1, 0, 0, (SCM stil), - "Return whether @var{stil} is empty ") + "Return whether @var{stil} is empty.") { Stencil *s = unsmob_stencil (stil); LY_ASSERT_SMOB (Stencil, stil, 1); @@ -84,13 +86,14 @@ LY_DEFINE (ly_stencil_combine_at_edge, "ly:stencil-combine-at-edge", SCM second, SCM padding, SCM minimum), - "Construct a stencil by putting @var{second} next to @var{first}. " - "@var{axis} can be 0 (x-axis) or 1 (y-axis), " - "@var{direction} can be -1 (left or down) or 1 (right or up). " - "The stencils are juxtaposed with @var{padding} as extra space. " - "If this puts the reference points closer than @var{minimum}, " - "they are moved by the latter amount." - "@var{first} and @var{second} may also be '() or #f.") + "Construct a stencil by putting @var{second} next to @var{first}." + " @var{axis} can be 0 (x-axis) or@tie{}1 (y-axis)." + " @var{direction} can be -1 (left or down) or@tie{}1 (right or" + " up). The stencils are juxtaposed with @var{padding} as extra" + " space. If this puts the reference points closer than" + " @var{minimum}, they are moved by the latter amount." + " @var{first} and @var{second} may also be @code{'()} or" + " @code{#f}.") { Stencil *s1 = unsmob_stencil (first); Stencil *s2 = unsmob_stencil (second); @@ -128,7 +131,7 @@ LY_DEFINE (ly_stencil_combine_at_edge, "ly:stencil-combine-at-edge", LY_DEFINE (ly_stencil_add, "ly:stencil-add", 0, 0, 1, (SCM args), - "Combine stencils. Takes any number of arguments.") + "Combine stencils. Takes any number of arguments.") { #define FUNC_NAME __FUNCTION__ SCM_VALIDATE_REST_ARGUMENT (args); @@ -156,22 +159,19 @@ LY_DEFINE (ly_stencil_add, "ly:stencil-add", LY_DEFINE (ly_make_stencil, "ly:make-stencil", 1, 2, 0, (SCM expr, SCM xext, SCM yext), - "Stencils are device independent output expressions. " - "They carry two pieces of information:\n" - + "Stencils are device independent output expressions." + " They carry two pieces of information:\n" + "\n" "@enumerate\n" - "@item\n" - "A specification of how to print this object. " - "This specification is processed by the output backends, " - "for example @file{scm/output-ps.scm}.\n" - + "A specification of how to print this object." + " This specification is processed by the output backends," + " for example @file{scm/output-ps.scm}.\n" + "\n" "@item\n" - "The vertical and horizontal extents of the object, " - "given as pairs. " - "If an extent is unspecified (or if you use " - "@code{(1000 . -1000)} as its value), it is taken to be empty.\n" - + "The vertical and horizontal extents of the object, given as" + " pairs. If an extent is unspecified (or if you use" + " @code{(1000 . -1000)} as its value), it is taken to be empty.\n" "@end enumerate\n") { SCM_ASSERT_TYPE (!scm_is_pair (expr) @@ -200,9 +200,9 @@ LY_DEFINE (ly_make_stencil, "ly:make-stencil", LY_DEFINE (ly_stencil_aligned_to, "ly:stencil-aligned-to", 3, 0, 0, (SCM stil, SCM axis, SCM dir), - "Align @var{stil} using its own extents. " - "@var{dir} is a number -1, 1 are left and right respectively. " - "Other values are interpolated (so 0 means the center).") + "Align @var{stil} using its own extents. @var{dir} is a number." + " @code{-1} and @code{1} are left and right, respectively." + " Other values are interpolated (so @code{0} means the center).") { LY_ASSERT_SMOB (Stencil, stil, 1); LY_ASSERT_TYPE (is_axis, axis, 2); @@ -217,7 +217,8 @@ LY_DEFINE (ly_stencil_aligned_to, "ly:stencil-aligned-to", LY_DEFINE (ly_stencil_fonts, "ly:stencil-fonts", 1, 0, 0, (SCM s), - " Analyse @var{s}, and return a list of fonts used in @var{s}.") + "Analyze @var{s}, and return a list of fonts used" + " in@tie{}@var{s}.") { LY_ASSERT_SMOB (Stencil, s, 1); Stencil *stil = unsmob_stencil (s); @@ -250,7 +251,8 @@ void stencil_interpret_in_scm (void *p, SCM expr) LY_DEFINE (ly_interpret_stencil_expression, "ly:interpret-stencil-expression", 4, 0, 0, (SCM expr, SCM func, SCM arg1, SCM offset), - "Parse EXPR, feed bits to FUNC with first arg ARG1") + "Parse @var{expr}, feed bits to @var{func} with first arg" + " @var{arg1} having offset @var{offset}.") { LY_ASSERT_TYPE (ly_is_procedure, func, 2); @@ -267,9 +269,10 @@ LY_DEFINE (ly_interpret_stencil_expression, "ly:interpret-stencil-expression", LY_DEFINE (ly_bracket, "ly:bracket", 4, 0, 0, (SCM a, SCM iv, SCM t, SCM p), - "Make a bracket in direction @var{a}. The extent of the bracket is " - "given by @var{iv}. The wings protude by an amount of @var{p}, which " - "may be negative. The thickness is given by @var{t}.") + "Make a bracket in direction@tie{}@var{a}. The extent of the" + " bracket is given by @var{iv}. The wings protude by an amount" + " of@tie{}@var{p}, which may be negative. The thickness is given" + " by@tie{}@var{t}.") { LY_ASSERT_TYPE (is_axis, a, 1); LY_ASSERT_TYPE (is_number_pair, iv, 2); @@ -284,7 +287,8 @@ LY_DEFINE (ly_bracket, "ly:bracket", LY_DEFINE (ly_stencil_rotate, "ly:stencil-rotate", 4, 0, 0, (SCM stil, SCM angle, SCM x, SCM y), - "Return a @var{stil} rotated @var{angle} degrees around point (@var{x}, @var{y}).") + "Return a stencil @var{stil} rotated @var{angle} degrees around" + " point (@var{x}, @var{y}).") { Stencil *s = unsmob_stencil (stil); LY_ASSERT_SMOB (Stencil, stil, 1); @@ -304,9 +308,8 @@ LY_DEFINE (ly_stencil_rotate, "ly:stencil-rotate", LY_DEFINE (ly_round_filled_box, "ly:round-filled-box", 3, 0, 0, (SCM xext, SCM yext, SCM blot), - "Make a @code{Stencil} " - "that prints a black box of dimensions @var{xext}, " - "@var{yext} and roundness @var{blot}.") + "Make a @code{Stencil} object that prints a black box of" + " dimensions @var{xext}, @var{yext} and roundness @var{blot}.") { LY_ASSERT_TYPE (is_number_pair, xext, 1); LY_ASSERT_TYPE (is_number_pair, yext, 2); @@ -319,7 +322,7 @@ LY_DEFINE (ly_round_filled_box, "ly:round-filled-box", LY_DEFINE (ly_register_stencil_expression, "ly:register-stencil-expression", 1, 0, 0, (SCM symbol), - "Add @var{symbol} as head of a stencil expression") + "Add @var{symbol} as head of a stencil expression.") { LY_ASSERT_TYPE (ly_is_symbol, symbol, 1); register_stencil_head (symbol); diff --git a/lily/stream-event-scheme.cc b/lily/stream-event-scheme.cc index 04df26a722..f578a8332a 100644 --- a/lily/stream-event-scheme.cc +++ b/lily/stream-event-scheme.cc @@ -10,7 +10,8 @@ LY_DEFINE (ly_make_stream_event, "ly:make-stream-event", 1, 1, 0, (SCM cl, SCM proplist), - "Creates a stream event of class @var{cl} with the given mutable property list.\n" ) + "Create a stream event of class @var{cl} with the given" + " mutable property list.") { LY_ASSERT_TYPE (ly_is_symbol, cl, 1); @@ -26,8 +27,8 @@ LY_DEFINE (ly_make_stream_event, "ly:make-stream-event", LY_DEFINE (ly_event_property, "ly:event-property", 2, 0, 0, (SCM sev, SCM sym), - "Get the property @var{sym} of stream event @var{mus}.\n" - "If @var{sym} is undefined, return @code{'()}.\n") + "Get the property @var{sym} of stream event @var{mus}." + " If @var{sym} is undefined, return @code{'()}.") { LY_ASSERT_SMOB (Stream_event, sev, 1); LY_ASSERT_TYPE (ly_is_symbol, sym, 2); @@ -49,7 +50,7 @@ LY_DEFINE (ly_event_set_property_x, "ly:event-set-property!", LY_DEFINE (ly_event_deep_copy, "ly:event-deep-copy", 1, 0, 0, (SCM m), - "Copy @var{m} and all sub expressions of @var{m}") + "Copy @var{m} and all sub expressions of@tie{}@var{m}.") { SCM copy = m; if (Stream_event *ev = unsmob_stream_event (m)) diff --git a/lily/system-scheme.cc b/lily/system-scheme.cc index d0b7cfc9b2..284dc4102c 100644 --- a/lily/system-scheme.cc +++ b/lily/system-scheme.cc @@ -13,8 +13,8 @@ LY_DEFINE (ly_system_print, "ly:system-print", 1, 0, 0, (SCM system), - "Draw the system and return the prob containing its " - "stencil.") + "Draw the system and return the prob containing its" + " stencil.") { Grob *me = unsmob_grob (system); System *me_system = dynamic_cast (me); @@ -25,9 +25,9 @@ LY_DEFINE (ly_system_print, "ly:system-print", LY_DEFINE (ly_system_stretch, "ly:system-stretch", 2, 0, 0, (SCM system, SCM amount_scm), - "Stretch the system vertically by the given amount. " - "This must be called before the system is drawn (for example " - "with ly:system-print).") + "Stretch the system vertically by the given amount." + " This must be called before the system is drawn (for example" + " with @code{ly:system-print}).") { Grob *me = unsmob_grob (system); Real amount = robust_scm2double (amount_scm, 0.0); diff --git a/lily/text-interface.cc b/lily/text-interface.cc index 0c514a35d8..de773b62ca 100644 --- a/lily/text-interface.cc +++ b/lily/text-interface.cc @@ -35,15 +35,14 @@ Text_interface::interpret_string (SCM layout_smob, } MAKE_SCHEME_CALLBACK_WITH_OPTARGS (Text_interface, interpret_markup, 3, 0, - "Convert a text markup into a stencil. " -"Takes 3 arguments, @var{layout}, @var{props} and @var{markup}. " -"\n\n" -"@var{layout} is a @code{\\layout} block; it may be obtained from a grob with " -"@code{ly:grob-layout}. @var{props} is a alist chain, ie. a list of alists. " -"This is typically obtained with " -"@code{(ly:grob-alist-chain (ly:layout-lookup layout 'text-font-defaults))}. " -"@var{markup} is the markup text to be processed. " - ); + "Convert a text markup into a stencil." +" Takes three arguments, @var{layout}, @var{props}, and @var{markup}.\n" +"\n" +"@var{layout} is a @code{\\layout} block; it may be obtained from a grob with" +" @code{ly:grob-layout}. @var{props} is a alist chain, ie. a list of alists." +" This is typically obtained with" +" @code{(ly:grob-alist-chain (ly:layout-lookup layout 'text-font-defaults))}." +" @var{markup} is the markup text to be processed."); SCM Text_interface::interpret_markup (SCM layout_smob, SCM props, SCM markup) { diff --git a/lily/text-metrics.cc b/lily/text-metrics.cc index 05b17fdfcc..c83f561dc7 100644 --- a/lily/text-metrics.cc +++ b/lily/text-metrics.cc @@ -50,7 +50,8 @@ lookup_tex_text_dimension (Font_metric *font, SCM text) LY_DEFINE (ly_load_text_dimensions, "ly:load-text-dimensions", 1, 0, 0, (SCM dimension_alist), - "Load dimensions from TeX in a (KEY . (W H D)) format alist") + "Load dimensions from @TeX{} in a @code{(KEY . (W H D))} format" + " alist.") { if (!text_dimension_hash_tab) { diff --git a/lily/translator-ctors.cc b/lily/translator-ctors.cc index f4eaeaf31a..c024abe388 100644 --- a/lily/translator-ctors.cc +++ b/lily/translator-ctors.cc @@ -19,7 +19,8 @@ Scheme_hash_table *global_translator_dict = 0; LY_DEFINE (get_all_translators, "ly:get-all-translators", 0, 0, 0, (), - "Return a list of all translator objects that may be instantiated. ") + "Return a list of all translator objects that may be" + " instantiated.") { SCM l = global_translator_dict ? global_translator_dict->to_alist () : SCM_EOL; diff --git a/lily/translator-scheme.cc b/lily/translator-scheme.cc index 31e7afa92e..71fa6af2c2 100644 --- a/lily/translator-scheme.cc +++ b/lily/translator-scheme.cc @@ -12,8 +12,8 @@ LY_DEFINE (ly_translator_name, "ly:translator-name", 1, 0, 0, (SCM trans), - "Return the type name of the translator object @var{trans}. " - "The name is a symbol.") + "Return the type name of the translator object @var{trans}." + " The name is a symbol.") { LY_ASSERT_SMOB (Translator, trans, 1); Translator *tr = unsmob_translator (trans); @@ -23,7 +23,7 @@ LY_DEFINE (ly_translator_name, "ly:translator-name", LY_DEFINE (ly_translator_description, "ly:translator-description", 1, 0, 0, (SCM me), - "Return an alist of properties of translator @var{me}.") + "Return an alist of properties of translator @var{me}.") { LY_ASSERT_SMOB (Translator, me, 1); Translator *tr = unsmob_translator (me); diff --git a/lily/translator.cc b/lily/translator.cc index ae1dfbe7ff..d0ed1e5213 100644 --- a/lily/translator.cc +++ b/lily/translator.cc @@ -132,7 +132,8 @@ ensure_listened_hash () LY_DEFINE (ly_get_listened_event_classes, "ly:get-listened-event-classes", 0, 0, 0, (), - "Returns a list of all event classes that some translator listens to.") + "Return a list of all event classes that some translator listens" + " to.") { ensure_listened_hash (); return ly_hash_table_keys (listened_event_class_table); diff --git a/scm/documentation-lib.scm b/scm/documentation-lib.scm index 5a0afbbf34..5dc35f25a9 100644 --- a/scm/documentation-lib.scm +++ b/scm/documentation-lib.scm @@ -78,9 +78,13 @@ . string-to-use) " (string-append - "\n@table @asis\n" + "\n" + "@quotation\n" + "@table @asis\n" (apply string-append (map one-item->texi items-alist)) - "\n@end table\n")) + "\n" + "@end table\n" + "@end quotation\n")) (define (texi-menu items-alist) "Generate what is between @menu and @end menu." -- 2.39.2