[
https://issues.apache.org/jira/browse/SOLR-14383?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17188885#comment-17188885
]
ASF subversion and git services commented on SOLR-14383:
--------------------------------------------------------
Commit 34da84c238f3aff57cd7bba8040ccf6f6d94cf15 in lucene-solr's branch
refs/heads/jira/SOLR-14383 from Chris M. Hostetter
[ https://gitbox.apache.org/repos/asf?p=lucene-solr.git;h=34da84c ]
Merge branch 'master' into jira/SOLR-14383
> Fix indexing-nested-documents.adoc XML/JSON examples to be accurate,
> consistent, and clear
> ------------------------------------------------------------------------------------------
>
> Key: SOLR-14383
> URL: https://issues.apache.org/jira/browse/SOLR-14383
> Project: Solr
> Issue Type: Sub-task
> Reporter: Chris M. Hostetter
> Assignee: Chris M. Hostetter
> Priority: Major
> Attachments: SOLR-14383.patch, SOLR-14383.patch, SOLR-14383.patch,
> SOLR-14383.patch
>
>
> As reported on solr-user@lucene by Peter Pimley...
> {noformat}
> The page "Indexing Nested Documents" has an XML example showing two
> different ways of adding nested documents:
> https://lucene.apache.org/solr/guide/8_5/indexing-nested-documents.html#xml-examples
> The text says:
> "It illustrates two styles of adding child documents: the first is
> associated via a field "comment" (preferred), and the second is done
> in the classic way now referred to as an "anonymous" or "unlabelled"
> child document."
> However in the XML directly below there is no field named "comment".
> There is one named "content" and another named "comments" (plural),
> but no field named "comment". In fact, looking at the Json example
> immediately below, I wonder if the XML element currently named
> "content" should be named "comments", and what is currently marked
> "comments" should be "content"?
> Secondly, in the Json example it says:
> "The labelled relationship here is one child document but could have
> been wrapped in array brackets."
> However in the actual Json, the parent document (ID=1) with a labelled
> relationship has two child documents (IDs 2 and 3), and they are
> already in array brackets.
> {noformat}
> * The 2 examples (XML and JSON) should be updated to contains *structurally*
> identical content, (ie: same number of documents, with same field values, and
> same hierarchical relationships) to focus on demonstrating the syntax
> differences (ie: things like the special {{\_childDocuments\_}} key in json)
> * The paragraphs describing the examples should be updated to:
> ** refer to the correct field names -- since both "comments" and "contents"
> fields exist in the examples, it's impossible for novice users to even
> udnerstand where th "typo" might be in the descriptions (I'm pretty
> knowledgeable about Solr and even i'm second guessing myself as to what the
> intent in these paragraphs are)
> ** refer to documents by {{"id"}} value, not just descriptors like "first"
> and "second"
> * it might be worth considering rewriting this section to use "callouts":
> https://asciidoctor.org/docs/user-manual/#callouts -- similar to how we use
> them in other sections like this:
> https://lucene.apache.org/solr/guide/8_5/uploading-data-with-index-handlers.html#sending-json-update-commands
--
This message was sent by Atlassian Jira
(v8.3.4#803005)
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscr...@lucene.apache.org
For additional commands, e-mail: issues-h...@lucene.apache.org
