Clarify some KDoc

src/main/kotlin/dev/stalla/PodcastRssParser.kt

@@ -31,6 +31,8 @@ import java.io.File
 import java.io.IOException
 import java.io.InputStream
 import javax.xml.parsers.DocumentBuilder
+import kotlin.contracts.InvocationKind
+import kotlin.contracts.contract
 
 /**
  * The main entry point to parse a podcast RSS feed. You can use
@@ -174,10 +176,14 @@ public object PodcastRssParser {
         builder
     }
 
-    private fun <T> Node.ifTagNameIs(tagName: String, block: () -> T): T? =
-        if (namespaceURI == null && nodeName == tagName) {
+    private fun <T> Node.ifTagNameIs(tagName: String, block: () -> T): T? {
+        contract {
+            callsInPlace(block, InvocationKind.AT_MOST_ONCE)
+        }
+        return if (namespaceURI == null && nodeName == tagName) {
             block()
         } else {
             null
         }
+    }
 }

src/main/kotlin/dev/stalla/model/Episode.kt

@@ -20,16 +20,16 @@ import java.time.temporal.TemporalAccessor
  * Direct instantiation in Java is discouraged. Use the [builder][Episode.Factory.builder]
  * method to obtain an [EpisodeBuilder] instance for expressive construction instead.
  *
- * @property title The RSS `<title>` field textContent.
- * @property link The RSS `<link>` field textContent.
- * @property description The RSS `<description>` field textContent.
- * @property author The RSS `<author>` field textContent
- * @property categories List of RSS `<category>` field contents.
- * @property comments The RSS `<comments>` field textContent.
+ * @property title The RSS `<title>` element text content.
+ * @property link The RSS `<link>` element text content.
+ * @property description The RSS `<description>` element text content.
+ * @property author The RSS `<author>` element text content
+ * @property categories List of RSS `<category>` element text contents.
+ * @property comments The RSS `<comments>` element text content.
  * @property enclosure The RSS `<enclosure>` element attributes wrapped in an [Enclosure] instance.
  * @property guid The RSS `<guid>` element wrapped in an [Guid] instance.
- * @property pubDate The RSS `<pubDate>` field textContent.
- * @property source The RSS `<source>` field textContent.
+ * @property pubDate The RSS `<pubDate>` element text content.
+ * @property source The RSS `<source>` element's text content.
  * @property content The data from the RSS 1.0 Content module namespace,
  *                   or null if no data from this namespace was found.
  * @property itunes The data from the iTunes namespace, or null if no data from this namespace was found.

src/main/kotlin/dev/stalla/model/HrefOnlyImage.kt

@@ -9,7 +9,7 @@ import dev.stalla.builder.validating.ValidatingHrefOnlyImageBuilder
  * Direct instantiation in Java is discouraged. Use the [builder][HrefOnlyImage.Factory.builder]
  * method to obtain an [HrefOnlyImageBuilder] instance for expressive construction instead.
  *
- * @property href The value of the `href` attribute. Represents the image URL.
+ * @property href The text content of the `href` attribute. Represents the image URL.
  *
  * @since 1.0.0
  */

src/main/kotlin/dev/stalla/model/Podcast.kt

@@ -19,18 +19,18 @@ import java.util.Locale
  * Direct instantiation in Java is discouraged. Use the [builder][Podcast.Factory.builder]
  * method to obtain a [PodcastBuilder] instance for expressive construction instead.
  *
- * @property title The RSS `<title>` field textContent.
- * @property link The RSS `<link>` field textContent.
- * @property description The RSS `<description>` field textContent.
- * @property pubDate The RSS `<pubDate>` field textContent.
- * @property lastBuildDate The RSS `<lastBuildDate>` field textContent.
- * @property language The RSS `<language>` field textContent.
- * @property generator The RSS `<generator>` field textContent.
- * @property copyright The RSS `<copyright>` field textContent.
- * @property docs The RSS `<docs>` field textContent.
- * @property managingEditor The RSS `<managingEditor>` field textContent.
- * @property webMaster The RSS `<webMaster>` field textContent.
- * @property ttl The RSS `<ttl>` field textContent.
+ * @property title The RSS `<title>` element text content.
+ * @property link The RSS `<link>` element text content.
+ * @property description The RSS `<description>` element text content.
+ * @property pubDate The RSS `<pubDate>` element text content.
+ * @property lastBuildDate The RSS `<lastBuildDate>` element text content.
+ * @property language The RSS `<language>` element text content.
+ * @property generator The RSS `<generator>` element text content.
+ * @property copyright The RSS `<copyright>` element text content.
+ * @property docs The RSS `<docs>` field element content.
+ * @property managingEditor The RSS `<managingEditor>` element text content.
+ * @property webMaster The RSS `<webMaster>` element text content.
+ * @property ttl The RSS `<ttl>` element text content.
  * @property image The RSS `<image>` element wrapped in an [RssImage] instance.
  * @property episodes List of [Episode] instances extracted from the `<item>` entries of the RSS feed.
  * @property itunes The data from the iTunes namespace, or null if no data from this namespace was found.

src/main/kotlin/dev/stalla/model/atom/Link.kt

@@ -11,13 +11,13 @@ import dev.stalla.model.MediaType
  * Direct instantiation in Java is discouraged. Use the [builder][Link.Factory.builder]
  * method to obtain a [LinkBuilder] instance for expressive construction instead.
  *
- * @property href The `href` attribute textContent of the `<atom:link>` element.
- * @property hrefLang The `hrefLang` attribute textContent of the `<atom:link>` element.
- * @property hrefResolved The `hrefResolved` attribute textContent of the `<atom:link>` element.
- * @property length The `length` attribute textContent of the `<atom:link>` element.
- * @property rel The `rel` attribute textContent of the `<atom:link>` element.
- * @property title The `title` attribute textContent of the `<atom:link>` element.
- * @property type The `type` attribute textContent of the `<atom:link>` element as a [MediaType].
+ * @property href The `href` attribute text content of the `<atom:link>` element.
+ * @property hrefLang The `hrefLang` attribute text content of the `<atom:link>` element.
+ * @property hrefResolved The `hrefResolved` attribute text content of the `<atom:link>` element.
+ * @property length The `length` attribute text content of the `<atom:link>` element.
+ * @property rel The `rel` attribute text content of the `<atom:link>` element.
+ * @property title The `title` attribute text content of the `<atom:link>` element.
+ * @property type The `type` attribute text content of the `<atom:link>` element as a [MediaType].
  *
  * @since 1.0.0
  */

src/main/kotlin/dev/stalla/model/bitlove/Bitlove.kt

@@ -10,7 +10,7 @@ import dev.stalla.model.BuilderFactory
  * Direct instantiation in Java is discouraged. Use the [builder][Bitlove.Factory.builder]
  * method to obtain an [EpisodeBitloveBuilder] instance for expressive construction instead.
  *
- * @property guid The `bitlove:guid` attribute for the RSS `<enclosure>` element.
+ * @property guid The `bitlove:guid` attribute text content for the RSS `<enclosure>` element.
  *
  * @since 1.0.0
  */

src/main/kotlin/dev/stalla/model/googleplay/EpisodeGoogleplay.kt

@@ -15,10 +15,10 @@ import dev.stalla.model.HrefOnlyImage
  * [XML Schema](https://www.google.com/schemas/play-podcasts/1.0/play-podcasts.xsd)
  * for the Google Play Podcasts extension
  *
- * @property author The `<googleplay:author>` field text content.
- * @property description The `<googleplay:description>` field text content.
- * @property explicit The value of the `<googleplay:explicit>` field text content as an [ExplicitType].
- * @property block The logical value of the `<googleplay:block>` field's text content.
+ * @property author The `<googleplay:author>` element text content.
+ * @property description The `<googleplay:description>` element text content.
+ * @property explicit The value of the `<googleplay:explicit>` element text content as an [ExplicitType].
+ * @property block The logical value of the `<googleplay:block>` element text content.
  * @property image The data from the `<googleplay:image>` element as an [HrefOnlyImage].
  *
  * @since 1.0.0

src/main/kotlin/dev/stalla/model/googleplay/PodcastGoogleplay.kt

@@ -15,14 +15,14 @@ import dev.stalla.model.HrefOnlyImage
  * Direct instantiation in Java is discouraged. Use the [builder][PodcastGoogleplay.Factory.builder]
  * method to obtain a [PodcastGoogleplayBuilder] instance for expressive construction instead.
  *
- * @property author The `<googleplay:author>` field text content.
- * @property email The `<googleplay:email>` field text content.
- * @property categories The list of `<googleplay:category>` element's field text contents as [GoogleplayCategory].
- * @property description The `<googleplay:description>` field text content.
- * @property explicit The logical value of the `<googleplay:explicit>` field's text content.
- * @property block The logical value of the `<googleplay:block>` field's text content.
+ * @property author The `<googleplay:author>` element text content.
+ * @property email The `<googleplay:email>` element text content.
+ * @property categories The list of `<googleplay:category>` element text contents as [GoogleplayCategory].
+ * @property description The `<googleplay:description>` element text content.
+ * @property explicit The logical value of the `<googleplay:explicit>` element text content.
+ * @property block The logical value of the `<googleplay:block>` element text content.
  * @property image The data from the `<googleplay:image>` element as an [HrefOnlyImage].
- * @property newFeedUrl The `<googleplay:newFeedUrl>` field text content.
+ * @property newFeedUrl The `<googleplay:newFeedUrl>` element text content.
  *
  * @since 1.0.0
  */

src/main/kotlin/dev/stalla/model/itunes/EpisodeItunes.kt

@@ -12,17 +12,17 @@ import dev.stalla.model.StyledDuration
  * Direct instantiation in Java is discouraged. Use the [builder][EpisodeItunes.Factory.builder]
  * method to obtain a [EpisodeItunesBuilder] instance for expressive construction instead.
  *
- * @property title The `<itunes:title>` field text content.
- * @property duration The value of the `<itunes:duration>` field text content as a [StyledDuration].
+ * @property title The `<itunes:title>` element text content.
+ * @property duration The value of the `<itunes:duration>` element text content as a [StyledDuration].
  * @property image The data from the `<itunes:image>` element as an [HrefOnlyImage].
- * @property explicit The logical value of the `<itunes:explicit>` field's text content.
- * @property block The logical value of the `<itunes:block>` field's text content.
- * @property season The numeric value of the `<itunes:season>` field's text content.
- * @property episode The numeric value of the `<itunes:episode>` field's text content.
- * @property episodeType The value of the `<itunes:episodeType>` field text content as an [EpisodeType].
- * @property author The `<itunes:author>` field text content.
- * @property subtitle The `<itunes:subtitle>` field text content.
- * @property summary The `<itunes:summary>` field text content.
+ * @property explicit The logical value of the `<itunes:explicit>` element text content.
+ * @property block The logical value of the `<itunes:block>` element text content.
+ * @property season The numeric value of the `<itunes:season>` element text content.
+ * @property episode The numeric value of the `<itunes:episode>` element text content.
+ * @property episodeType The value of the `<itunes:episodeType>` element text content as an [EpisodeType].
+ * @property author The `<itunes:author>` element text content.
+ * @property subtitle The `<itunes:subtitle>` element text content.
+ * @property summary The `<itunes:summary>` element text content.
  *
  * @since 1.0.0
  */

src/main/kotlin/dev/stalla/model/itunes/PodcastItunes.kt

@@ -11,19 +11,19 @@ import dev.stalla.model.HrefOnlyImage
  * Direct instantiation in Java is discouraged. Use the [builder][PodcastItunes.Factory.builder]
  * method to obtain a [PodcastItunesBuilder] instance for expressive construction instead.
  *
- * @property subtitle The `<itunes:subtitle>` field text content.
- * @property summary The `<itunes:summary>` field text content.
+ * @property subtitle The `<itunes:subtitle>` element text content.
+ * @property summary The `<itunes:summary>` element text content.
  * @property image The data from the `<itunes:image>` element as an [HrefOnlyImage].
- * @property keywords The `<itunes:keywords>` field text content.
- * @property author The `<itunes:author>` field text content.
- * @property categories The list of `<itunes:category>` element's field text contents as [ItunesCategory].
- * @property explicit The logical value of the `<itunes:explicit>` field's text content.
- * @property block The logical value of the `<itunes:block>` field's text content.
- * @property complete The logical value of the `<itunes:complete>` field's text content.
- * @property type The value of the `<itunes:type>` field text content as a [ShowType].
+ * @property keywords The `<itunes:keywords>` element text content.
+ * @property author The `<itunes:author>` element text content.
+ * @property categories The list of `<itunes:category>` element text contents as [ItunesCategory].
+ * @property explicit The logical value of the `<itunes:explicit>` element text content.
+ * @property block The logical value of the `<itunes:block>` element text content.
+ * @property complete The logical value of the `<itunes:complete>` element text content.
+ * @property type The value of the `<itunes:type>` element text content as a [ShowType].
  * @property owner The `<itunes:owner>` elements data as an [ItunesOwner].
- * @property title The `<itunes:title>` field text content.
- * @property newFeedUrl The `<itunes:new-feed-url>` field text content.
+ * @property title The `<itunes:title>` element text content.
+ * @property newFeedUrl The `<itunes:new-feed-url>` element text content.
  *
  * @since 1.0.0
  */

src/main/kotlin/dev/stalla/model/podlove/SimpleChapter.kt

@@ -11,10 +11,10 @@ import dev.stalla.model.BuilderFactory
  * Direct instantiation in Java is discouraged. Use the [builder][SimpleChapter.Factory.builder] method
  * to obtain an [EpisodePodloveSimpleChapterBuilder] instance for expressive construction instead.
  *
- * @property start The value of the chapter's `start` attribute.
- * @property title The value of the chapter's `title` attribute.
- * @property href The value of the chapter's `href` attribute.
- * @property image The value of the chapter's `image` attribute.
+ * @property start The value of the chapter's `start` attribute text content.
+ * @property title The value of the chapter's `title` attribute text content.
+ * @property href The value of the chapter's `href` attribute text content.
+ * @property image The value of the chapter's `image` attribute text content.
  *
  * @since 1.0.0
  */

src/main/kotlin/dev/stalla/model/rss/Enclosure.kt

@@ -11,9 +11,9 @@ import dev.stalla.model.MediaType
  * Direct instantiation in Java is discouraged. Use the [builder][Enclosure.Factory.builder]
  * method to obtain an [EpisodeEnclosureBuilder] instance for expressive construction instead.
  *
- * @property url The `url` attribute textContent of the RSS `<enclosure>` element.
- * @property length The `length` attribute textContent of the RSS `<enclosure>` element. The media length in seconds.
- * @property type The `type` attribute textContent of the RSS `<enclosure>` element as a [MediaType].
+ * @property url The `url` attribute text content of the RSS `<enclosure>` element.
+ * @property length The `length` attribute text content of the RSS `<enclosure>` element. The media length in seconds.
+ * @property type The `type` attribute text content of the RSS `<enclosure>` element as a [MediaType].
  *
  * @since 1.0.0
  */

src/main/kotlin/dev/stalla/model/rss/Guid.kt

@@ -11,7 +11,7 @@ import dev.stalla.model.BuilderFactory
  * method to obtain an [EpisodeGuidBuilder] instance for expressive construction instead.
  *
  * @property guid The text content of the element.
- * @property isPermalink The boolean interpretation of the `isPermalink` attribute.
+ * @property isPermalink The boolean interpretation of the `isPermalink` attribute text content.
  *
  * @since 1.0.0
  */

src/main/kotlin/dev/stalla/model/rss/RssImage.kt

@@ -24,14 +24,14 @@ import dev.stalla.model.BuilderFactory
  * Direct instantiation in Java is discouraged. Use the [builder][RssImage.Factory.builder]
  * method to obtain an [RssImageBuilder] instance for expressive construction instead.
  *
- * @property url The value of an RSS `<url>` element inside an `<image>`. Represents the image URL.
- * @property title The value of an RSS `<title>` element inside an `<image>`.
+ * @property url The text content of an RSS `<url>` element inside an `<image>`. Represents the image URL.
+ * @property title The text content of an RSS `<title>` element inside an `<image>`.
  *                 **Must** match the containing podcast's or episode's `title`.
- * @property link The value of an RSS `<link>` element inside an `<image>`.
+ * @property link The text content of an RSS `<link>` element inside an `<image>`.
  *                **Must** match the containing podcast's or episode's `link`.
- * @property width The numeric value of an RSS `<width>` element inside an `<image>` element.
- * @property height The numeric value of an RSS `<height>` element inside an `<image>` element.
- * @property description The value of an RSS `<description>` element inside an `<image>`.
+ * @property width The numeric interpretation of the text content of an RSS `<width>` element inside an `<image>` element.
+ * @property height The numeric interpretation of the text content of an RSS `<height>` element inside an `<image>` element.
+ * @property description The text content of an RSS `<description>` element inside an `<image>`.
  *
  * @since 1.0.0
  */