Improve documentation

[pdvrieze]

trafficstars

The library has less focus on documentation than ideal. Better documentation is desirable.

[djc]

I'm trying to get this to work, but so far I'm failing. I'd be happy to contribute a little example if I manage to get one to work...

I added net.devrieze:xmlutil:0.8.0 to my Gradle dependencies (and jcenter() is in the repositories), but after doing so I cannot access anything from nl.adaptivity.* in IDEA. Any clues on what might be wrong?

[pdvrieze]

I think the problem may be that you need to use an architecture specific package: net.devrieze:xmlutil-jvm:0.8.0 net.devrieze:xmlutil-android:0.8.0

The plain one is a multiplatform package that should bring in the parts where needed.

[altavir]

One of the problems with contributing is unusual code formatting rules. If I call auto-format, I will immediately break the formatting (I use official code-style). Do you plan to adopt official code-style in future?

[pdvrieze]

Yes. I've just added the gradle property. The style in the project actually already follows the official style, but there is a lot of older code that probably doesn't.

[altavir]

Happy to hear it. I was really confused with non-standard closing braces position.

[pdvrieze]

I'm trying to reformat stuff at the moment. There is a lot of poor cruft due to the old formatter (like breaks where not needed). I also tend not to have autoformating enabled. I get really annoyed by poor line breaking algorithms that sometimes don't even give more horizontal space.

[ZacSweers]

A simple sample project would go a long way for this

[altavir]

You are welcome to use our GDML connector. It uses a custom plugin to load dependencies, but I should not be a problem,

[pdvrieze]

I'm currently working on a significantly re-engineered version (in the dev / dev-1.4 branches). It actually works by creating a detailed tree structure for the type and then using that for serialization/deserialization. This cleans up the code massively and goes a long way into correctness as well. With 1.4 I'll also see about using dokka documentation. As to examples, a good place to look is in the test code, but I'll see if some more documentation can be there.

Please note that I'll be bringing the API in line with kotlinx.serialization-1.0 and will also be changing the configuration in a way that allows for attaching a policy that is used to determine various properties, including handling missing values, determining how lists are serialized, etc.

[Doomsdayrs]

What the documentation lacks currently is a if X then y.

If I have x issue, what is y I must do?

Take the below xml

<repository version="1.2"
            xmlns="http://www.gtk.org/introspection/core/1.0"
            xmlns:c="http://www.gtk.org/introspection/c/1.0"
            xmlns:glib="http://www.gtk.org/introspection/glib/1.0">
  <include name="GObject" version="2.0"/>
    <include name="Pango" version="1.0"/>
  <include name="cairo" version="1.0"/>
  <!-- More excluded -->
</repository>

And my code

@Serializable
@XmlSerialName("repository", "http://www.gtk.org/introspection/core/1.0", "")
data class Repository(
	@XmlElement(false)
	val version: String,

	val include: Include
)

@Serializable
data class Include(
	val name: String,
	val version: String
)

And the error

Exception in thread "main" nl.adaptivity.xmlutil.serialization.UnknownXmlFieldException: Could not find a field for name {http://www.gtk.org/introspection/core/1.0}repository/{http://www.gtk.org/introspection/core/1.0}include
  candidates: version, {http://www.gtk.org/introspection/core/1.0}Include at position Line number = 9

How do I know what I must do here? There is no if x then y in the documentation.

[pdvrieze]

Good idea.

For this particular one, the answer is to specify the name on either the type or the property (@XmlSerialName only - @Serialname is invisible to the format) - tags by default take their name from the type, look at the default naming policy. documentation.

[Kryomancer]

I'm having difficulty trying to make use of this library, could you please post even one basic use example? The examples directory seems to only include weird edge cases and it's incredibly difficult to glean basic usage from them,

[pdvrieze]

@Kryomancer For the most basic usage you follow the documentation of the base serialization library, and then use XML rather than Json. After that there are many ways to customize the generated xml.

[yuroyami]

I have been scouting the repo for an hour now but I couldn't set foot on an actual starting point to deserialize a simple string-resource XML using XmlUtil since I couldn't find any basic parsing example. I believe a basic parsing example is the most crucial thing to include when it comes to documentation.

Btw, thank you for your honorable hard work!

[pdvrieze]

@yuroyami I just pushed some changes to the readme, including two hello-world example (encoding and decoding). There is some expected familiarity with the kotlinx.serialization library though. The documentation mainly discusses specifics to xml.

[yuroyami]

@pdvrieze Thank you so much !