You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@lucy.apache.org by "Dan Markham (Created) (JIRA)" <ji...@apache.org> on 2011/11/27 08:08:40 UTC
[lucy-issues] [jira] [Created] (LUCY-194) Small Doc patch
Small Doc patch
---------------
Key: LUCY-194
URL: https://issues.apache.org/jira/browse/LUCY-194
Project: Lucy
Issue Type: Improvement
Reporter: Dan Markham
Priority: Trivial
--- a/core/Lucy/Plan/Schema.cfh
+++ b/core/Lucy/Plan/Schema.cfh
@@ -81,7 +81,7 @@ class Lucy::Plan::Schema inherits Lucy::Object::Obj {
public uint32_t
Num_Fields(Schema *self);
- /** Return all the Schema's field names as an array.
+ /** Return all the Schema's field names as an arrayref.
*/
public incremented VArray*
All_Fields(Schema *self);
--
--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators: https://issues.apache.org/jira/secure/ContactAdministrators!default.jspa
For more information on JIRA, see: http://www.atlassian.com/software/jira
[lucy-issues] [jira] [Commented] (LUCY-194) Small Doc patch
Posted by "Marvin Humphrey (Commented) (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/LUCY-194?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13157725#comment-13157725 ]
Marvin Humphrey commented on LUCY-194:
--------------------------------------
To be precise, the function returns a Lucy::Object::VArray. However, thanks
the the Clownfish Perl bindings, VArray return values get converted to Perl
arrayrefs on the fly, so our Perl users don't have to know anything about
VArrays.
The problem here is that documentation in our clownfish header files will be
used to autogenerate docs for all bindings -- so Ruby, Python, C users, etc,
they will all see the same text. The term "arrayref" won't work for any of
them: Ruby users will get a Ruby array, Python users a Python list, C users an
actual VArray, and so on.
Father Chrysostomos made a similar point in 2009, flagging a function which
was then documented as returning a "list", but actually returned an arrayref.
We [agreed|http://www.rectangular.com/pipermail/kinosearch/2009-May/007037.html] that "array" was an acceptable compromise:
{quote}
> Current KS never deals in list context. When the documentation says "an
> array", it means an "array ref". This was an artifact of me trying to set
> things up so that the same documentation text could be shared by multiple
> binding languages; "array ref" isn't right in the context of Java, C, etc.
I have no problem understanding ‘array’. Let’s use it. :-)
> I might have to do something asinine like use #AN_ARRAY# and swap in the
> name of choice for the bindings.
I don’t see that as asinine, but it might be easier just to put a note
somewhere that arrays are always references.
{quote}
(I never wound up taking up that last suggestion, because I didn't think such
a note would ever by spotted given how users access reference docs, and a
patch never arrived to force the issue.)
I'll bet this will keep coming up until we finally implement the #AN_ARRAY#
trick. We should probably discuss that on the dev list, then open an issue.
> Small Doc patch
> ---------------
>
> Key: LUCY-194
> URL: https://issues.apache.org/jira/browse/LUCY-194
> Project: Lucy
> Issue Type: Improvement
> Reporter: Dan Markham
> Priority: Trivial
> Attachments: 0001-Doc-update-for-Lucy-Plan-Schema.patch
>
>
> --- a/core/Lucy/Plan/Schema.cfh
> +++ b/core/Lucy/Plan/Schema.cfh
> @@ -81,7 +81,7 @@ class Lucy::Plan::Schema inherits Lucy::Object::Obj {
> public uint32_t
> Num_Fields(Schema *self);
>
> - /** Return all the Schema's field names as an array.
> + /** Return all the Schema's field names as an arrayref.
> */
> public incremented VArray*
> All_Fields(Schema *self);
> --
--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators: https://issues.apache.org/jira/secure/ContactAdministrators!default.jspa
For more information on JIRA, see: http://www.atlassian.com/software/jira
[lucy-issues] [jira] [Updated] (LUCY-194) Small Doc patch
Posted by "Dan Markham (Updated) (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/LUCY-194?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Dan Markham updated LUCY-194:
-----------------------------
Attachment: 0001-Doc-update-for-Lucy-Plan-Schema.patch
> Small Doc patch
> ---------------
>
> Key: LUCY-194
> URL: https://issues.apache.org/jira/browse/LUCY-194
> Project: Lucy
> Issue Type: Improvement
> Reporter: Dan Markham
> Priority: Trivial
> Attachments: 0001-Doc-update-for-Lucy-Plan-Schema.patch
>
>
> --- a/core/Lucy/Plan/Schema.cfh
> +++ b/core/Lucy/Plan/Schema.cfh
> @@ -81,7 +81,7 @@ class Lucy::Plan::Schema inherits Lucy::Object::Obj {
> public uint32_t
> Num_Fields(Schema *self);
>
> - /** Return all the Schema's field names as an array.
> + /** Return all the Schema's field names as an arrayref.
> */
> public incremented VArray*
> All_Fields(Schema *self);
> --
--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators: https://issues.apache.org/jira/secure/ContactAdministrators!default.jspa
For more information on JIRA, see: http://www.atlassian.com/software/jira
[lucy-issues] [jira] [Commented] (LUCY-194) Small Doc patch
Posted by "Dan Markham (Commented) (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/LUCY-194?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13158059#comment-13158059 ]
Dan Markham commented on LUCY-194:
----------------------------------
I don't feel strongly either.
I did code up my perl wrong the first time based on my understanding of the doc..
@list = $schema->all_fields();
didn't take to long to find my issue.
> Small Doc patch
> ---------------
>
> Key: LUCY-194
> URL: https://issues.apache.org/jira/browse/LUCY-194
> Project: Lucy
> Issue Type: Improvement
> Reporter: Dan Markham
> Priority: Trivial
> Attachments: 0001-Doc-update-for-Lucy-Plan-Schema.patch
>
>
> --- a/core/Lucy/Plan/Schema.cfh
> +++ b/core/Lucy/Plan/Schema.cfh
> @@ -81,7 +81,7 @@ class Lucy::Plan::Schema inherits Lucy::Object::Obj {
> public uint32_t
> Num_Fields(Schema *self);
>
> - /** Return all the Schema's field names as an array.
> + /** Return all the Schema's field names as an arrayref.
> */
> public incremented VArray*
> All_Fields(Schema *self);
> --
--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators: https://issues.apache.org/jira/secure/ContactAdministrators!default.jspa
For more information on JIRA, see: http://www.atlassian.com/software/jira