Merge branch 'sm/1059_support_variable_extension' of github.com:opens…

…rp/android-fhir into sm/1059_support_variable_extension
google · Jul 27, 2022 · 680ca34 · 680ca34
2 parents 30a833b + 86907e6
commit 680ca34
Show file tree

Hide file tree

Showing 630 changed files with 17,014 additions and 16,248 deletions.
diff --git a/datacapture/src/main/java/com/google/android/fhir/datacapture/DataCaptureConfig.kt b/datacapture/src/main/java/com/google/android/fhir/datacapture/DataCaptureConfig.kt
@@ -54,9 +54,9 @@ data class DataCaptureConfig(
 
   /**
    * A class that can provide the [DataCaptureConfig] for the Structured Data Capture Library. To do
-   * this, implement the {@link DataCaptureConfig.Provider} interface on your [Application] class.
-   * You should provide the same configuration throughout the lifecycle of your application. The
-   * library may cache the configuration and different configurations will be ignored.
+   * this, implement the [DataCaptureConfig.Provider] interface on your [Application] class. You
+   * should provide the same configuration throughout the lifecycle of your application. The library
+   * may cache the configuration and different configurations will be ignored.
    */
   interface Provider {
     fun getDataCaptureConfig(): DataCaptureConfig

diff --git a/datacapture/src/main/java/com/google/android/fhir/datacapture/QuestionnaireFragment.kt b/datacapture/src/main/java/com/google/android/fhir/datacapture/QuestionnaireFragment.kt
@@ -33,9 +33,18 @@ import androidx.recyclerview.widget.RecyclerView
 import com.google.android.fhir.datacapture.views.QuestionnaireItemViewHolderFactory
 import org.hl7.fhir.r4.model.Questionnaire
 
+/**
+ * A [Fragment] for displaying FHIR Questionnaires and getting user responses as FHIR
+ * QuestionnareResponses.
+ *
+ * For more information, see the
+ * [QuestionnaireFragment](https://github.com/google/android-fhir/wiki/SDCL%3A-Use-QuestionnaireFragment)
+ * developer guide.
+ */
 open class QuestionnaireFragment : Fragment() {
   private val viewModel: QuestionnaireViewModel by viewModels()
 
+  /** @suppress */
   override fun onCreateView(
     inflater: LayoutInflater,
     container: ViewGroup?,
@@ -55,6 +64,7 @@ open class QuestionnaireFragment : Fragment() {
     }
   }
 
+  /** @suppress */
   override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
     val recyclerView = view.findViewById<RecyclerView>(R.id.recycler_view)
     val paginationPreviousButton = view.findViewById<View>(R.id.pagination_previous_button)
@@ -107,18 +117,33 @@ open class QuestionnaireFragment : Fragment() {
   }
 
   /**
-   * Returns a list of [QuestionnaireItemViewHolderFactoryMatcher]s that provide custom views for
-   * rendering items in the questionnaire. User-provided custom views will take precedence over
-   * canonical views provided by the library. If multiple
-   * [QuestionnaireItemViewHolderFactoryMatcher] are applicable for the same item, the behavior is
-   * undefined (any of them may be selected).
+   * Override this method to specify when custom questionnaire components should be used. It should
+   * return a [List] of [QuestionnaireItemViewHolderFactoryMatcher]s which are used to evaluate
+   * whether a custom [QuestionnaireItemViewHolderFactory] should be used to render a given
+   * questionnaire item.
+   *
+   * User-provided custom views take precedence over canonical views provided by the library. If
+   * multiple [QuestionnaireItemViewHolderFactoryMatcher] are applicable for the same item, the
+   * behavior is undefined (any of them may be selected).
+   *
+   * See the
+   * [developer guide](https://github.com/google/android-fhir/wiki/SDCL:-Customize-how-a-Questionnaire-is-displayed#custom-questionnaire-components)
+   * for more information.
    */
   open fun getCustomQuestionnaireItemViewHolderFactoryMatchers() =
     emptyList<QuestionnaireItemViewHolderFactoryMatcher>()
 
-  // Returns the current questionnaire response
+  /**
+   * Returns a [QuestionnaireResponse][org.hl7.fhir.r4.model.QuestionnaireResponse] populated with
+   * any answers that are present on the rendered [QuestionnaireFragment] when it is called.
+   */
   fun getQuestionnaireResponse() = viewModel.getQuestionnaireResponse()
 
+  /**
+   * Extras that can be passed to [QuestionnaireFragment] to define its behavior. When you create a
+   * QuestionnaireFragment, one of [EXTRA_QUESTIONNAIRE_JSON_URI] or
+   * [EXTRA_QUESTIONNAIRE_JSON_STRING] is required.
+   */
   companion object {
     /**
      * A JSON encoded string extra for a questionnaire. This should only be used for questionnaires
@@ -130,29 +155,28 @@ open class QuestionnaireFragment : Fragment() {
      * precedence.
      */
     const val EXTRA_QUESTIONNAIRE_JSON_STRING = "questionnaire"
+
     /**
-     * A [Uri] extra for streaming a JSON encoded questionnaire.
+     * A [URI][android.net.Uri] extra for streaming a JSON encoded questionnaire.
      *
      * This is required unless [EXTRA_QUESTIONNAIRE_JSON_STRING] is provided.
      *
      * If this and [EXTRA_QUESTIONNAIRE_JSON_STRING] are provided, this extra takes precedence.
      */
     const val EXTRA_QUESTIONNAIRE_JSON_URI = "questionnaire-uri"
+
     /**
      * A JSON encoded string extra for a prefilled questionnaire response. This should only be used
      * for questionnaire response with size at most 512KB. For large questionnaire response, use
      * [EXTRA_QUESTIONNAIRE_RESPONSE_JSON_URI].
      *
-     * This is required unless [EXTRA_QUESTIONNAIRE_RESPONSE_JSON_URI] is provided.
-     *
      * If this and [EXTRA_QUESTIONNAIRE_RESPONSE_JSON_URI] are provided,
      * [EXTRA_QUESTIONNAIRE_RESPONSE_JSON_URI] takes precedence.
      */
     const val EXTRA_QUESTIONNAIRE_RESPONSE_JSON_STRING = "questionnaire-response"
+
     /**
-     * A [Uri] extra for streaming a JSON encoded questionnaire response.
-     *
-     * This is required unless [EXTRA_QUESTIONNAIRE_RESPONSE_JSON_STRING] is provided.
+     * A [URI][android.net.Uri] extra for streaming a JSON encoded questionnaire response.
      *
      * If this and [EXTRA_QUESTIONNAIRE_RESPONSE_JSON_STRING] are provided, this extra takes
      * precedence.
@@ -164,12 +188,19 @@ open class QuestionnaireFragment : Fragment() {
 
   /**
    * Data class that holds a matcher function ([matches]) which evaluates whether a given [factory]
-   * should be used in creating a
-   * [com.google.android.fhir.datacapture.views.QuestionnaireItemViewHolder] that displays the given
-   * [Questionnaire.QuestionnaireItemComponent]
+   * should be used to display a given [Questionnaire.QuestionnaireItemComponent].
+   *
+   * See the
+   * [developer guide](https://github.com/google/android-fhir/wiki/SDCL:-Customize-how-a-Questionnaire-is-displayed#custom-questionnaire-components)
+   * for more information.
    */
   data class QuestionnaireItemViewHolderFactoryMatcher(
+    /** The custom [QuestionnaireItemViewHolderFactory] to use. */
     val factory: QuestionnaireItemViewHolderFactory,
-    val matches: (Questionnaire.QuestionnaireItemComponent) -> Boolean
+    /**
+     * A predicate function which, given a [Questionnaire.QuestionnaireItemComponent], returns true
+     * if the factory should apply to that item.
+     */
+    val matches: (Questionnaire.QuestionnaireItemComponent) -> Boolean,
   )
 }
diff --git a/datacapture/src/main/java/com/google/android/fhir/datacapture/mapping/ResourceMapper.kt b/datacapture/src/main/java/com/google/android/fhir/datacapture/mapping/ResourceMapper.kt
@@ -54,20 +54,21 @@ import org.hl7.fhir.r4.utils.FHIRPathEngine
 import org.hl7.fhir.r4.utils.StructureMapUtilities
 
 /**
- * Maps [QuestionnaireResponse] s to FHIR resources and vice versa.
+ * Maps a [QuestionnaireResponse] to FHIR resources and vice versa.
  *
  * The process of converting [QuestionnaireResponse] s to other FHIR resources is called
  * [extraction](http://build.fhir.org/ig/HL7/sdc/extraction.html). The reverse process of converting
  * existing FHIR resources to [QuestionnaireResponse] s to be used to pre-fill the UI is called
  * [population](http://build.fhir.org/ig/HL7/sdc/populate.html).
  *
- * [Definition-based extraction](http://build.fhir.org/ig/HL7/sdc/extraction.html#definition-based-extraction)
+ * This class supports
+ * [Definition-based extraction](http://build.fhir.org/ig/HL7/sdc/extraction.html#definition-based-extraction),
+ * [StructureMap-based extraction](http://hl7.org/fhir/uv/sdc/extraction.html#structuremap-based-extraction),
  * and
- * [expression-based population](http://build.fhir.org/ig/HL7/sdc/populate.html#expression-based-population)
- * are used because these approaches are generic enough to work with any FHIR resource types, and at
- * the same time relatively easy to implement.
+ * [expression-based population](http://build.fhir.org/ig/HL7/sdc/populate.html#expression-based-population).
  *
- * WARNING: This is not production-ready.
+ * See the [developer guide](https://github.com/google/android-fhir/wiki/SDCL%3A-Use-ResourceMapper)
+ * for more information.
  */
 object ResourceMapper {
 
@@ -77,15 +78,19 @@ object ResourceMapper {
     }
 
   /**
-   * Extract a FHIR resource from the [questionnaire] and [questionnaireResponse].
+   * Extract FHIR resources from a [questionnaire] and [questionnaireResponse].
    *
-   * This method supports both Definition-based and StructureMap-based extraction.
+   * This method will perform
+   * [StructureMap-based extraction](http://hl7.org/fhir/uv/sdc/extraction.html#structuremap-based-extraction)
+   * if the [Questionnaire] specified by [questionnaire] includes a `targetStructureMap` extension.
+   * In this case [structureMapExtractionContext] is required; extraction will fail and an empty
+   * [Bundle] is returned if [structureMapExtractionContext] is not provided.
    *
-   * StructureMap-based extraction will be invoked if the [Questionnaire] declares a
-   * targetStructureMap extension otherwise Definition-based extraction is used. StructureMap-based
-   * extraction will fail and an empty [Bundle] will be returned if the [structureMapProvider] is
-   * not passed.
+   * Otherwise, this method will perform
+   * [Definition-based extraction](http://hl7.org/fhir/uv/sdc/extraction.html#definition-based-extraction).
    *
+   * @param questionnaire A [Questionnaire] with data extraction extensions.
+   * @param questionnaireResponse A [QuestionnaireResponse] with answers for [questionnaire].
    * @param structureMapExtractionContext The [IWorkerContext] may be used along with
    * [StructureMapUtilities] to parse the script and convert it into [StructureMap].
    *
@@ -175,8 +180,10 @@ object ResourceMapper {
   }
 
   /**
-   * Returns a `QuestionnaireResponse` to the [questionnaire] that is pre-filled from the
-   * [resources] See http://build.fhir.org/ig/HL7/sdc/populate.html#expression-based-population.
+   * Performs
+   * [Expression-based population](http://build.fhir.org/ig/HL7/sdc/populate.html#expression-based-population)
+   * and returns a [QuestionnaireResponse] for the [questionnaire] that is populated from the
+   * [resources].
    */
   suspend fun populate(
     questionnaire: Questionnaire,

diff --git a/...rc/main/java/com/google/android/fhir/datacapture/mapping/StructureMapExtractionContext.kt b/...rc/main/java/com/google/android/fhir/datacapture/mapping/StructureMapExtractionContext.kt
@@ -21,8 +21,26 @@ import org.hl7.fhir.r4.context.IWorkerContext
 import org.hl7.fhir.r4.model.StructureMap
 import org.hl7.fhir.r4.utils.StructureMapUtilities
 
+/**
+ * Data used during StructureMap-based extraction.
+ */
 data class StructureMapExtractionContext(
+  /** The application context. */
   val context: Context,
+  /**
+   * Optionally pass a custom version of [StructureMapUtilities.ITransformerServices] to support
+   * specific use cases.
+   **/
   val transformSupportServices: StructureMapUtilities.ITransformerServices? = null,
+  /**
+   * A lambda function which returns a [StructureMap]. Depending on your app this could be
+   * hard-coded or use the [String] parameter to fetch the appropriate structure map.
+   *
+   * @param String The canonical URL for the Structure Map referenced in the
+   * [Target structure map extension](http://hl7.org/fhir/uv/sdc/StructureDefinition-sdc-questionnaire-targetStructureMap.html)
+   * of the questionnaire.
+   * @param IWorkerContext May be used with other HAPI FHIR classes, like using
+   * [StructureMapUtilities.parse] to parse content in the FHIR Mapping Language.
+   */
   val structureMapProvider: (suspend (String, IWorkerContext) -> StructureMap?)
 )
diff --git a/...ure/data-capture/com.google.android.fhir.datacapture.common.datatype/as-string-value.html b/...ure/data-capture/com.google.android.fhir.datacapture.common.datatype/as-string-value.html
@@ -2,35 +2,34 @@
   <head>
     <meta name="viewport" content="width=device-width, initial-scale=1" charset="UTF-8">
     <title>asStringValue</title>
-<link href="../../../../images/logo-icon.svg" rel="icon" type="image/svg"><script>var pathToRoot = "../../";</script><script type="text/javascript" src="../../scripts/sourceset_dependencies.js" async="async"></script><link href="../../styles/style.css" rel="Stylesheet"><link href="../../styles/logo-styles.css" rel="Stylesheet"><link href="../../styles/jetbrains-mono.css" rel="Stylesheet"><link href="../../styles/main.css" rel="Stylesheet"><script type="text/javascript" src="../../scripts/clipboard.js" async="async"></script><script type="text/javascript" src="../../scripts/navigation-loader.js" async="async"></script><script type="text/javascript" src="../../scripts/platform-content-handler.js" async="async"></script><script type="text/javascript" src="../../scripts/main.js" async="async"></script>  </head>
+<link href="../../images/logo-icon.svg" rel="icon" type="image/svg"><script>var pathToRoot = "../../";</script>    <script>const storage = localStorage.getItem("dokka-dark-mode")
+const savedDarkMode = storage ? JSON.parse(storage) : false
+if(savedDarkMode === true){
+    document.getElementsByTagName("html")[0].classList.add("theme-dark")
+}</script>
+<script type="text/javascript" src="../../scripts/sourceset_dependencies.js" async="async"></script><link href="../../styles/style.css" rel="Stylesheet"><link href="../../styles/jetbrains-mono.css" rel="Stylesheet"><link href="../../styles/main.css" rel="Stylesheet"><link href="../../styles/prism.css" rel="Stylesheet"><link href="../../styles/logo-styles.css" rel="Stylesheet"><script type="text/javascript" src="../../scripts/clipboard.js" async="async"></script><script type="text/javascript" src="../../scripts/navigation-loader.js" async="async"></script><script type="text/javascript" src="../../scripts/platform-content-handler.js" async="async"></script><script type="text/javascript" src="../../scripts/main.js" defer="defer"></script><script type="text/javascript" src="../../scripts/prism.js" async="async"></script>  </head>
   <body>
+    <div class="navigation-wrapper" id="navigation-wrapper">
+      <div id="leftToggler"><span class="icon-toggler"></span></div>
+      <div class="library-name"><a href="../../index.html">data-capture</a></div>
+      <div>0.1.0-beta03</div>
+      <div class="pull-right d-flex"><button id="theme-toggle-button"><span id="theme-toggle"></span></button>
+        <div id="searchBar"></div>
+      </div>
+    </div>
     <div id="container">
-      <div id="leftColumn"><a href="../../index.html">
-          <div id="logo"></div>
-        </a>
-        <div id="paneSearch"></div>
+      <div id="leftColumn">
         <div id="sideMenu"></div>
       </div>
       <div id="main">
-        <div id="leftToggler"><span class="icon-toggler"></span></div>
-<script type="text/javascript" src="../../scripts/main.js"></script>        <div class="main-content" id="content" pageIds="data-capture::com.google.android.fhir.datacapture.common.datatype//asStringValue/org.hl7.fhir.r4.model.Type#/PointingToDeclaration//616728252">
-          <div class="navigation-wrapper" id="navigation-wrapper">
-            <div class="breadcrumbs"><a href="../../index.html">data-capture</a>/<a href="index.html">com.google.android.fhir.datacapture.common.datatype</a>/<a href="as-string-value.html">asStringValue</a></div>
-            <div class="pull-right d-flex">
-              <div id="searchBar"></div>
-            </div>
-          </div>
+        <div class="main-content" id="content" pageIds="data-capture::com.google.android.fhir.datacapture.common.datatype//asStringValue/Type#/PointingToDeclaration//-991669519">
+          <div class="breadcrumbs"><a href="../../index.html">data-capture</a>/<a href="index.html">com.google.android.fhir.datacapture.common.datatype</a>/<a href="as-string-value.html">asStringValue</a></div>
           <div class="cover ">
-            <h1 class="cover"><span>as</span><wbr></wbr><span>String</span><wbr></wbr><span>Value</span></h1>
+            <h1 class="cover"><span>as</span><wbr></wbr><span>String</span><wbr></wbr><span><span>Value</span></span></h1>
           </div>
-<div class="divergent-group" data-filterable-current=":datacapture:dokkaHtml/release" data-filterable-set=":datacapture:dokkaHtml/release"><div class="with-platform-tags"><span class="pull-right"></span></div>
-
-  <div>
-    <div class="platform-hinted " data-platform-hinted="data-platform-hinted"><div class="content sourceset-depenent-content" data-active="" data-togglable=":datacapture:dokkaHtml/release"><div class="symbol monospace">fun <a href="https://hapifhir.io/hapi-fhir/apidocs/hapi-fhir-structures-r4/org/hl7/fhir/r4/model/Type.html">Type</a>.<a href="as-string-value.html">asStringValue</a>(): <a href="https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html">String</a><span class="top-right-position"><span class="copy-icon"></span><div class="copy-popup-wrapper popup-to-left"><span class="copy-popup-icon"></span><span>Content copied to clipboard</span></div></span></div></div></div>
-  </div>
-<p class="paragraph">Returns the string representation of a <a href="https://hapifhir.io/hapi-fhir/apidocs/hapi-fhir-structures-r4/org/hl7/fhir/r4/model/PrimitiveType.html">PrimitiveType</a>.</p><p>If the type isn't a [PrimitiveType], an empty string is returned.</div>
+          <div class="platform-hinted " data-platform-hinted="data-platform-hinted"><div class="content sourceset-depenent-content" data-active="" data-togglable=":datacapture:dokkaHtml/main"><div class="symbol monospace"><span class="token keyword"></span><span class="token keyword">fun </span><span data-unresolved-link="/&amp;lt;ERROR CLASS&amp;gt;///PointingToDeclaration/">&lt;ERROR CLASS&gt;</span><span class="token punctuation">.</span><a href="as-string-value.html"><span class="token function">asStringValue</span></a><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token operator">: </span><a href="https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html">String</a><span class="top-right-position"><span class="copy-icon"></span><div class="copy-popup-wrapper popup-to-left"><span class="copy-popup-icon"></span><span>Content copied to clipboard</span></div></span></div><p class="paragraph">Returns the string representation of a PrimitiveType.</p><p>If the type isn't a [PrimitiveType], an empty string is returned.</div></div>
         </div>
-        <div class="footer"><span class="go-to-top-icon"><a href="#content"></a></span><span>© 2022 Copyright</span><span class="pull-right"><span>Generated by </span><a href="https://github.com/Kotlin/dokka"><span>dokka</span><span class="padded-icon"></span></a></span></div>
+        <div class="footer"><span class="go-to-top-icon"><a href="#content" id="go-to-top-link"></a></span><span>© 2022 Copyright</span><span class="pull-right"><span>Generated by </span><a href="https://github.com/Kotlin/dokka"><span>dokka</span><span class="padded-icon"></span></a></span></div>
       </div>
     </div>
   </body>