RFR: JDK-8179022 Add serialization spec as markdown
Magnus Ihse Bursie
magnus.ihse.bursie at oracle.com
Thu Apr 20 18:47:13 UTC 2017
On 2017-04-20 15:59, Alan Bateman wrote:
> On 20/04/2017 14:49, Magnus Ihse Bursie wrote:
>
>> Here's the first step towards fixing JDK-8177434
>> <https://bugs.openjdk.java.net/browse/JDK-8177434>. A framework is
>> added for converting markdown specs to html using pandoc. The Java
>> serialization spec is added in markdown format as a proof of concept.
>> I also reintroduced the functionality to enable full docs if all
>> prerequisites are present.
>>
>> Note that this fix is dependent on the patch for JDK-8178038 et al
>> that is currently out for review. The webrev is created with that
>> patch as baseline.
>>
>> This fix is part of JEP 299. I intend to push it to jdk9.
>>
>> Here's an example of the generated output:
>> http://cr.openjdk.java.net/~ihse/JDK-8179022-javadoc-output-demo/specs/serialization/
>>
>>
>> Bug: https://bugs.openjdk.java.net/browse/JDK-8179022
>> WebRev:
>> http://cr.openjdk.java.net/~ihse/JDK-8179022-add-markdown-serialization-spec/webrev.01
> I just skimmed this and notice this adds class.gif with output that I
> think is serialver. This tool has been changed in JDK 9 to drop the
> GUI and so this image and the reference to the "Show" button are now
> obsolete. I'm sure you don't want want to get into issues like this
> but we will need to submit a few bugs to ensure that some of the dusty
> documents are updated.
You are right that I do not want to make any substantial changes to the
documentation. I have made an effort to make sure the markdown is of a
high quality (like any other source code), so that it should be easy to
read and update. In this process I noticed a few minor issues (like
syntactic errors in the examples, or incorrect/inconsistent formatting)
which I have fixed.
I have also noticed some things that sound like they need to be updated,
like the serialver stuff. I'm no expert on serialization, but perhaps I
can have an offline chat with someone who are, and come with a couple of
suggestions on things to improve with the documentation.
---
I just noticed that I had missed to do "hg add" so webrev did not pick
up my new script that creates the pandoc bundle. Here's an updated
webrev that added this:
http://cr.openjdk.java.net/~ihse/JDK-8179022-add-markdown-serialization-spec/webrev.02
/Magnus
>
> -Alan
More information about the core-libs-dev
mailing list