Neil Puttock wrote:
> No, since you've changed the names of function arguments while leaving
> the original names in the body of the function...
(facepalm)
how's this then?
- Mark
From 66f5bf48a8708cabf878501fea6fa90e9fc31e69 Mon Sep 17 00:00:00 2001
From: Mark Polesky <markpole...@yahoo.com>
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
_______________________________________________
lilypond-devel mailing list
lilypond-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/lilypond-devel
