search

Leonidas-from-XIV / node-xml2js

XML to JavaScript object converter.
MIT License
4.89k stars 606 forks source link

Document the format of the returned result #278

Open FagnerMartinsBrack opened 8 years ago

FagnerMartinsBrack commented 8 years ago

I couldn't find in the first lines of the README the documentation of the format that xml2js returns, only examples of how to use it. The format is important and should be on top because it defines the contract that is supported by the project and what should one expect when developing something that pass a xml2js result. For new starters, that is a must.

tflanagan commented 8 years ago

By vertue of being v0.X, you really can't expect a 100% stable input/output.

But, back to your suggestion, PRs are welcome :)

FagnerMartinsBrack commented 8 years ago

I didn't send a PR because I am not aware of what the author believes it's worth publicizing. It's less about a stable in/out between versions and more about what can be relied upon in a single minor version below version 0 for the current developed code.

In reality version 0 should not exist as long as the module is the more popular than just the original developer and its inner circle. Version 1 starts when a considerable amount of people rely on it. With that in mind this package should not be v0 but v1 instead.

Leonidas-from-XIV commented 8 years ago

The reason there is no demonstration on how the output looks like is because the options allow customization to such a point where it is tricky to document all possible variants. This is caused by the fact that when I took over the project the output format was quite random and dependent on the input data. Over time I added options to make it more static, but kept compatibility with the old way. I have adopted a policy of avoiding default setting inside the 0.1.x/0.2.x/0.4.x series. In a similar spirit, I still have things documented that people really shouldn't use anymore. Should just delete that from the README.

On a related note, I have planned to create "proper" canonical representation that would type-check if you'd define a type hierarchy, but I have that stuff on a separate local branch and hardly get time to work on this. Some of the legacy options of 0.1 might have to go away completely, though. But I guess some people use them because they are convenient.

tl;dr: Patches welcome I guess. Situation is admittedly not optimal.

FagnerMartinsBrack commented 8 years ago

I still have things documented that people really shouldn't use anymore. Should just delete that from the README.

I had no idea that some things are documented but should not be used, this should not take too much effort since it's just text removal (not code).

Patches welcome I guess

The problem is that, in this context, without domain knowledge of the project it is impossible to provide a proper PR to update anything, that's why I opened the issue. If at least somebody could provide information about what should be the "correct" or "default" format that the project uses, then maybe me or somebody else can send a PR documenting that. If that makes sense, of course.