Blog Scaladoc tables #959

janekdb · 2018-10-03T11:34:56Z

No description provided.

janekdb · 2018-10-03T11:36:27Z

Despite the branch name there is no part two. This is it!

Philippus · 2018-10-03T12:22:57Z

blog/_posts/2018-10-03-scaladoc-tables.md

+
+### A Simple Example
+
+The markdown for tables follows Github Markdown Flavored markdown with some restrictions.


GitHub Flavored Markdown

maybe include a link to https://github.github.com/gfm/ ?

Philippus · 2018-10-03T12:23:32Z

blog/_posts/2018-10-03-scaladoc-tables.md

+
+### GitHub Flavored Markdown Conformance
+
+Scaladoc tables support the [Github Flavored Markdown Spec Table Extension](https://github.github.com/gfm/#tables-extension-).


typo: GitHub

Philippus · 2018-10-03T12:25:44Z

blog/_posts/2018-10-03-scaladoc-tables.md

+<img alt="Example Table 2"
+     src="/resources/img/blog/scaladoc-tables/example-table-2.png">
+
+Breaking content over several lines is not supported in GHFM tables. Use a `<br/>` tag or go with HTML tables if you have needs beyond the simple tables supported by GHFM.


I think they prefer GFM for short: https://github.github.com/gfm/#what-is-github-flavored-markdown-

Philippus · 2018-10-03T12:26:03Z

blog/_posts/2018-10-03-scaladoc-tables.md

+
+### Including pipe (`|`) in content.
+
+Scala 2.12.8 supports the [escaping of the cell delimiter in cell content](https://github.com/scala/scala/pull/7247) with `\|`.


will support

Philippus

I've added some notes.

janekdb · 2018-10-03T15:54:09Z

@Philippus All your comments have been addressed. Kindly review.

SethTisue · 2018-10-03T16:05:55Z

Perhaps the post should say something, near the end, about what Scala 3 / Dotty supports or will support?

ashawley · 2018-10-03T16:07:20Z

blog/_posts/2018-10-03-scaladoc-tables.md

+This is how the above markdown renders,
+
+<img alt="Example Table 1"
+     src="/resources/img/blog/scaladoc-tables/example-table-1.png">


Jekyll supports an image syntax

![Example Table 1](/resources/img/blog/scaladoc-tables/example-table-1.png)

@ashawley Thanks! Changes made to both images.

janekdb · 2018-10-03T16:20:07Z

Perhaps the post should say something, near the end, about what Scala 3 / Dotty supports or will support?

@SethTisue If I can be supplied with the text I can add it now, otherwise I'll need to research it.

ashawley · 2018-10-03T16:20:32Z

This is exciting news and very good documentation, but maybe most of the material should be added to https://docs.scala-lang.org/overviews/scaladoc/for-library-authors.html

The images don't render very well on this site, maybe they'll look better on docs.scala-lang.org?

janekdb · 2018-10-03T16:22:02Z

@ashawley - I'm happy to take some time and update https://docs.scala-lang.org/overviews/scaladoc/for-library-authors.html later.

janekdb · 2018-10-03T16:24:29Z

This is how the image looks using the docker command, Image scaling appears to be present which I'm guessing is controlled by jekyll. The images seem okay for the level of the communique!

ashawley · 2018-10-03T16:32:25Z

The first one was the one I was more concerned with:

janekdb · 2018-10-03T16:37:19Z

@ashawley Do you know how to turn off resizing of images?

ashawley · 2018-10-03T16:39:32Z

I looked, but couldn't figure it out.

janekdb · 2018-10-03T16:41:59Z

I don't intend to look into the jekyll image control so reviewers please list any further changes required.

ashawley · 2018-10-03T16:45:40Z

It's a CSS issue with the new site, and not intrinsically a Jekyll issue.

SethTisue · 2018-10-03T16:52:38Z

If I can be supplied with the text I can add it now, otherwise I'll need to research it.

see
scala/scala#6043 (comment)

ashawley · 2018-10-03T18:04:58Z

blog/_posts/2018-10-03-scaladoc-tables.md

+title: "Introducing Scaladoc Tables"
+---
+
+Scala 2.12.7 adds support for markdown tables in Scaladoc comments.


Will it be added in 2.13? Library authors who cross-compile on 2.11 should avoid for now?

Library authors should only publish 2.12 docs or later?

It's been merged to 2.13.x IIRC. I feel advising not to use a feature that is only present from 2.12 onwards when cross compiling to 2.11 is overly prescriptive so I vote to not mention this.

Agree, doesn't seem like there's a reason to dissuade library authors, but maybe just mention that "library authors who use the table syntax will need to only publish from 2.12"?

It's been merged to 2.13.x IIRC

(it has, but after M5 was released)

@ashawley I mentioned the graceful degradation forward compatibility with 2.11 in a new section.

janekdb · 2018-10-03T18:31:41Z

@SethTisue I've gone dotty over dotty...

Philippus · 2018-10-03T18:34:56Z

blog/_posts/2018-10-03-scaladoc-tables.md

+
+### More Examples
+
+For a smorgasbord of examples take a look at [examples](http://janekdb.github.io/scala/PR-7247/scala/test/scaladoc/tables/code/index.html).


quite an expensive rookworst :)

Rookworsts on me!

Not actually me.

janekdb · 2018-10-04T10:29:12Z

@SethTisue @ashawley @Philippus - All changes addressed. Last change was to fix up some wonky wording in the Scala 2.11 and dotty sections. All done. Ready for review.

Philippus · 2018-10-04T10:45:02Z

blog/_posts/2018-10-04-scaladoc-tables.md

+
+### Dotty and Scala 3
+
+With `dotty` now boosting it's share of the development horizon it's important to place GFM into a [dottydoc](https://dotty.epfl.ch/docs/usage/dottydoc.html) and hence Scaladoc 3 context.


Philippus · 2018-10-04T10:45:17Z

blog/_posts/2018-10-04-scaladoc-tables.md

+
+With `dotty` now boosting it's share of the development horizon it's important to place GFM into a [dottydoc](https://dotty.epfl.ch/docs/usage/dottydoc.html) and hence Scaladoc 3 context.
+
+In overview `dottydoc` supports the currrent Scaladoc 2.12 MediaWiki flavored markdown, but it also supports more contemporary flavors of markdown.


typo: currrent -> current

Philippus · 2018-10-04T10:46:20Z

blog/_posts/2018-10-04-scaladoc-tables.md

+
+Within the realm of tables markdown `dottydoc` supports some extensions via the [flexmark-java table extension](https://github.com/vsch/flexmark-java/wiki/Tables-Extension).
+
+[flexmark-java](https://github.com/vsch/flexmark-java) allow tables to be defined using a more expressive variant of GFM table markdown. Tables you create now will have a route to being reused for `dottydoc` API documentation.


janekdb · 2018-10-04T11:28:41Z

@Philippus All requested changes made.

Philippus · 2018-10-04T11:29:51Z

blog/_posts/2018-10-04-scaladoc-tables.md

+
+### A Simple Example
+
+The markdown for tables follows [GitHub Markdown Flavored Markdown](https://github.github.com/gfm/) with some restrictions.


GitHub Flavored Markdown

Philippus

nice work! ty

janekdb · 2018-10-04T11:42:03Z

@Philippus Thanks for review comments.

@SethTisue - No pending review comments.

janekdb · 2018-10-04T11:52:34Z

Pushed one more fix
Within the realm of tables markdown -> Within the realm of table markdown

SethTisue · 2018-10-04T14:18:47Z

https://twitter.com/scala_lang/status/1047853269630902274

🎉

janekdb · 2018-10-04T14:46:42Z

Yay!

janekdb requested a review from SethTisue October 3, 2018 11:35

janekdb mentioned this pull request Oct 3, 2018

Add Scaladoc tables scala/scala#6043

Merged

28 tasks

Philippus reviewed Oct 3, 2018

View reviewed changes

Philippus requested changes Oct 3, 2018

View reviewed changes

janekdb force-pushed the topic/scaladoc-tables-part-one branch from ebd8896 to 105aa87 Compare October 3, 2018 15:52

SethTisue approved these changes Oct 3, 2018

View reviewed changes

ashawley reviewed Oct 3, 2018

View reviewed changes

janekdb force-pushed the topic/scaladoc-tables-part-one branch from 105aa87 to fd7b2c6 Compare October 3, 2018 16:10

ashawley reviewed Oct 3, 2018

View reviewed changes

janekdb force-pushed the topic/scaladoc-tables-part-one branch from fd7b2c6 to 364f2e4 Compare October 3, 2018 18:29

Philippus reviewed Oct 3, 2018

View reviewed changes

janekdb force-pushed the topic/scaladoc-tables-part-one branch 2 times, most recently from 3942586 to 9a59e12 Compare October 4, 2018 10:26

Philippus reviewed Oct 4, 2018

View reviewed changes

janekdb force-pushed the topic/scaladoc-tables-part-one branch from 9a59e12 to f26ef4b Compare October 4, 2018 11:28

Philippus reviewed Oct 4, 2018

View reviewed changes

janekdb force-pushed the topic/scaladoc-tables-part-one branch from f26ef4b to cb245d3 Compare October 4, 2018 11:36

Philippus approved these changes Oct 4, 2018

View reviewed changes

Blog Scaladoc tables

974c65b

janekdb force-pushed the topic/scaladoc-tables-part-one branch from cb245d3 to 974c65b Compare October 4, 2018 11:51

SethTisue merged commit dff9fb9 into scala:master Oct 4, 2018


		### A Simple Example

		The markdown for tables follows Github Markdown Flavored markdown with some restrictions.


		### GitHub Flavored Markdown Conformance

		Scaladoc tables support the [Github Flavored Markdown Spec Table Extension](https://github.github.com/gfm/#tables-extension-).


		### Including pipe (`\|`) in content.

		Scala 2.12.8 supports the [escaping of the cell delimiter in cell content](https://github.com/scala/scala/pull/7247) with `\\|`.


		### More Examples

		For a smorgasbord of examples take a look at [examples](http://janekdb.github.io/scala/PR-7247/scala/test/scaladoc/tables/code/index.html).


		### Dotty and Scala 3

		With `dotty` now boosting it's share of the development horizon it's important to place GFM into a [dottydoc](https://dotty.epfl.ch/docs/usage/dottydoc.html) and hence Scaladoc 3 context.


		With `dotty` now boosting it's share of the development horizon it's important to place GFM into a [dottydoc](https://dotty.epfl.ch/docs/usage/dottydoc.html) and hence Scaladoc 3 context.

		In overview `dottydoc` supports the currrent Scaladoc 2.12 MediaWiki flavored markdown, but it also supports more contemporary flavors of markdown.


		Within the realm of tables markdown `dottydoc` supports some extensions via the [flexmark-java table extension](https://github.com/vsch/flexmark-java/wiki/Tables-Extension).

		[flexmark-java](https://github.com/vsch/flexmark-java) allow tables to be defined using a more expressive variant of GFM table markdown. Tables you create now will have a route to being reused for `dottydoc` API documentation.


		### A Simple Example

		The markdown for tables follows [GitHub Markdown Flavored Markdown](https://github.github.com/gfm/) with some restrictions.

Blog Scaladoc tables #959

Blog Scaladoc tables #959

Uh oh!

Conversation

janekdb commented Oct 3, 2018

Uh oh!

janekdb commented Oct 3, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Philippus left a comment

Choose a reason for hiding this comment

Uh oh!

janekdb commented Oct 3, 2018

Uh oh!

SethTisue commented Oct 3, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

janekdb commented Oct 3, 2018

Uh oh!

ashawley commented Oct 3, 2018

Uh oh!

janekdb commented Oct 3, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

janekdb commented Oct 3, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ashawley commented Oct 3, 2018

Uh oh!

janekdb commented Oct 3, 2018

Uh oh!

ashawley commented Oct 3, 2018

Uh oh!

janekdb commented Oct 3, 2018

Uh oh!

ashawley commented Oct 3, 2018

Uh oh!

SethTisue commented Oct 3, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

janekdb commented Oct 3, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

janekdb commented Oct 4, 2018

Uh oh!

Choose a reason for hiding this comment

janekdb commented Oct 3, 2018 •

edited

Loading

janekdb commented Oct 3, 2018 •

edited

Loading

janekdb commented Oct 4, 2018 •

edited

Loading