From 66f5bf48a8708cabf878501fea6fa90e9fc31e69 Mon Sep 17 00:00:00 2001 From: Mark Polesky Date: Sun, 23 Aug 2009 17:33:23 -0700 Subject: [PATCH] Docs: IR 4 Scheme functions: Improve docstrings. --- lily/context-scheme.cc | 57 +++++++++++++++++++++++++---------------------- 1 files changed, 30 insertions(+), 27 deletions(-) diff --git a/lily/context-scheme.cc b/lily/context-scheme.cc index aef5404..c81eec8 100644 --- a/lily/context-scheme.cc +++ b/lily/context-scheme.cc @@ -13,9 +13,10 @@ 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 @dots{}}" - " return the string @code{one}.") + "Return the ID string of @var{context}, or an empty string" + " if not found." + " i.e., for @code{\\context Voice = one @dots{}} return the" + " string @code{one}.") { Context *tr = unsmob_context (context); @@ -38,32 +39,33 @@ 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" + 2, 0, 0, (SCM context, SCM grob), + "Return the definition of @var{grob} (a symbol) within" " @var{context} as an alist.") { Context *tr = unsmob_context (context); - + LY_ASSERT_SMOB (Context, context, 1); - LY_ASSERT_TYPE (ly_is_symbol, name, 2); + LY_ASSERT_TYPE (ly_is_symbol, grob, 2); - return updated_grob_properties (tr, name); + return updated_grob_properties (tr, grob); } 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 @var{grob} is extended" - " with @var{eltprop} (if @var{val} is specified) or reverted" - " (if unspecified).") + 3, 1, 0, (SCM context, SCM grob, SCM property, SCM value), + "Equivalent to" + " @code{\\override context.grob property = value} if" + " @var{value} is given; or" + " @code{\\revert context.grob property} if @var{value} is" + " not given. @var{grob} and @var{property} are symbols.") { Context *tg = unsmob_context (context); LY_ASSERT_SMOB (Context, context, 1); LY_ASSERT_TYPE (ly_is_symbol, grob, 2); - LY_ASSERT_TYPE (ly_is_symbol, eltprop, 3); + LY_ASSERT_TYPE (ly_is_symbol, property, 3); - execute_pushpop_property (tg, grob, eltprop, val); + execute_pushpop_property (tg, grob, property, value); return SCM_UNSPECIFIED; } @@ -80,16 +82,16 @@ 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}.") + 3, 0, 0, (SCM context, SCM property, SCM value), + "Set @var{property} (a symbol) to @var{value} in" + " @var{context}.") { LY_ASSERT_SMOB (Context, context, 1); - LY_ASSERT_TYPE (ly_is_symbol, name, 2); + LY_ASSERT_TYPE (ly_is_symbol, property, 2); Context *tr = unsmob_context (context); - tr->set_property (name, val); + tr->set_property (property, value); return SCM_UNSPECIFIED; } @@ -112,15 +114,15 @@ LY_DEFINE (ly_context_property_where_defined, "ly:context-property-where-defined return SCM_EOL; } -LY_DEFINE (ly_context_unset_property, "ly:context-unset-property", 2, 0, 0, - (SCM context, SCM name), - "Unset value of property @var{name} in context @var{context}.") +LY_DEFINE (ly_context_unset_property, "ly:context-unset-property", + 2, 0, 0, (SCM context, SCM property), + "Unset value of @var{property} (a symbol) in @var{context}.") { LY_ASSERT_SMOB (Context, context, 1); - LY_ASSERT_TYPE (ly_is_symbol, name, 2); + LY_ASSERT_TYPE (ly_is_symbol, property, 2); Context *tr = unsmob_context (context); - tr->unset_property (name); + tr->unset_property (property); return SCM_UNSPECIFIED; } @@ -141,8 +143,9 @@ 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.") + "Return the closest parent of @var{context} with the name or" + " alias @var{name} (a symbol). Return @code{#f} if not" + " found.") { LY_ASSERT_SMOB (Context, context, 1); LY_ASSERT_TYPE (ly_is_symbol, name, 2); -- 1.6.4.msysgit.0