updating toStandaloneHtml and toHtml kdocs with more detailed information

Author: Jolanrensen

core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/format.kt

@@ -758,14 +758,18 @@ public typealias CellFormatter<C> = FormattingDsl.(cell: C) -> CellAttributes?
  *
  * Call [toHtml] or [toStandaloneHtml] to get the HTML representation of the [DataFrame].
  *
+ * In Jupyter kernel (Kotlin Notebook) environments, you can often output this class directly.
+ * Use [toHtml] or [toStandaloneHtml] when this produces unexpected results.
+ *
  * You can apply further formatting to this [FormattedFrame] by calling [format()][FormattedFrame.format] once again.
  */
 public class FormattedFrame<T>(internal val df: DataFrame<T>, internal val formatter: RowColFormatter<T, *>? = null) {
 
     /**
      * Returns a [DataFrameHtmlData] without additional definitions.
-     * Can be rendered in Jupyter kernel (Notebook) environments or other environments that already have
+     * Can be rendered in Jupyter kernel (Kotlin Notebook) environments or other environments that already have
      * CSS- and script definitions for DataFrame.
+     *
      * Use [toStandaloneHtml] if you need the [DataFrameHtmlData] to include CSS- and script definitions.
      *
      * By default, cell content is formatted as text
@@ -781,6 +785,8 @@ public class FormattedFrame<T>(internal val df: DataFrame<T>, internal val forma
     /**
      * Returns a [DataFrameHtmlData] with CSS- and script definitions for DataFrame.
      *
+     * Use [toHtml] if you don't need the [DataFrameHtmlData] to include CSS- and script definitions.
+     *
      * The [DataFrameHtmlData] can be saved as an *.html file and displayed in the browser.
      * If you save it as a file and find it in the project tree,
      * the ["Open in browser"](https://www.jetbrains.com/help/idea/editing-html-files.html#ws_html_preview_output_procedure)
@@ -789,6 +795,10 @@ public class FormattedFrame<T>(internal val df: DataFrame<T>, internal val forma
      * By default, cell content is formatted as text
      * Use [RenderedContent.media][media] or [IMG], [IFRAME] if you need custom HTML inside a cell.
      *
+     * __NOTE:__ In Kotlin Notebook, output [FormattedFrame] directly, or use [toHtml],
+     * as that environment already has CSS- and script definitions for DataFrame.
+     * Using [toStandaloneHtml] might produce unexpected results.
+     *
      * @param [configuration] The [DisplayConfiguration] to use as a base for this [FormattedFrame].
      *   Default: [DisplayConfiguration.DEFAULT].
      * @see toHtml

core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/io/html.kt

@@ -559,17 +559,30 @@ public fun <T> DataFrame<T>.toStandaloneHTML(
 ): DataFrameHtmlData = toStandaloneHtml(configuration, cellRenderer, getFooter)
 
 /**
- * By default, cell content is formatted as text
- * Use [RenderedContent.media] or [IMG], [IFRAME] if you need custom HTML inside a cell.
+ * Returns a [DataFrameHtmlData] with CSS- and script definitions for DataFrame.
  *
  * To change the formatting of certain cells or columns in the dataframe,
  * use [DataFrame.format].
  *
+ * Use [toHtml] if you don't need the [DataFrameHtmlData] to include CSS- and script definitions.
+ *
  * The [DataFrameHtmlData] can be saved as an *.html file and displayed in the browser.
  * If you save it as a file and find it in the project tree,
  * the ["Open in browser"](https://www.jetbrains.com/help/idea/editing-html-files.html#ws_html_preview_output_procedure)
  * feature of IntelliJ IDEA will automatically reload the file content when it's updated.
- * @return DataFrameHtmlData with table script and css definitions
+ *
+ * By default, cell content is formatted as text
+ * Use [RenderedContent.media] or [IMG], [IFRAME] if you need custom HTML inside a cell.
+ *
+ * __NOTE:__ In Kotlin Notebook, output [DataFrame] directly, or use [toHtml],
+ * as that environment already has CSS- and script definitions for DataFrame.
+ * Using [toStandaloneHtml] might produce unexpected results.
+ *
+ * @param [configuration] The [DisplayConfiguration] to use. Default: [DisplayConfiguration.DEFAULT].
+ * @param [cellRenderer] Mostly for internal usage, use [DefaultCellRenderer] if unsure.
+ * @param [getFooter] Allows you to specify how to render the footer text beneath the dataframe.
+ *   Default: `"DataFrame [rows x cols]"`
+ * @see toHtml
  */
 public fun <T> DataFrame<T>.toStandaloneHtml(
     configuration: DisplayConfiguration = DisplayConfiguration.DEFAULT,
@@ -578,13 +591,23 @@ public fun <T> DataFrame<T>.toStandaloneHtml(
 ): DataFrameHtmlData = toHtml(configuration, cellRenderer, getFooter).withTableDefinitions()
 
 /**
- * By default, cell content is formatted as text
- * Use [RenderedContent.media] or [IMG], [IFRAME] if you need custom HTML inside a cell.
+ * Returns a [DataFrameHtmlData] without additional definitions.
+ * Can be rendered in Jupyter kernel (Kotlin Notebook) environments or other environments that already have
+ * CSS- and script definitions for DataFrame.
  *
  * To change the formatting of certain cells or columns in the dataframe,
  * use [DataFrame.format].
  *
- * @return DataFrameHtmlData without additional definitions. Can be rendered in Jupyter kernel environments
+ * Use [toStandaloneHtml] if you need the [DataFrameHtmlData] to include CSS- and script definitions.
+ *
+ * By default, cell content is formatted as text
+ * Use [RenderedContent.media] or [IMG], [IFRAME] if you need custom HTML inside a cell.
+ *
+ * @param [configuration] The [DisplayConfiguration] to use. Default: [DisplayConfiguration.DEFAULT].
+ * @param [cellRenderer] Mostly for internal usage, use [DefaultCellRenderer] if unsure.
+ * @param [getFooter] Allows you to specify how to render the footer text beneath the dataframe.
+ *   Default: `"DataFrame [rows x cols]"`
+ * @see toStandaloneHtml
  */
 public fun <T> DataFrame<T>.toHtml(
     configuration: DisplayConfiguration = DisplayConfiguration.DEFAULT,