search

apiaryio / gavel2html

Renders HTML diff from Gavel.js output
MIT License
0 stars 0 forks source link

There is no documentation #7

Closed honzajavorek closed 3 years ago

honzajavorek commented 8 years ago

The README just isn't enough. I'm failing to understand how the library works. Issues:

I would love to add the information, but unfortunately I'm not able to do so, because I don't understand the library myself. I would appreciate if @netmilk @kuba-kubula (as authors) or @XVincentX (as a recent user) could answer at least some of the questions. Feel free to add them as comment here, I'll gladly compile a nice README out of it later.

artem-zakharchenko commented 5 years ago

Hi. I will try to elaborate on the questions above using the power of reverse engineering.

If the library works also without Gavel, what are the benefits of actually passing the Gavel output then?

The gavelResult the library accepts it not the entire Gavel.js output, but a portion relevant to the rendered field. See:

const Gavel2html = require('gavel2html'

const renderer = new Gavel2html({
  dataExpected: `body: ''`
  dataReal: `body: { "foo": "bar" }`,
  gavelResult: {
    // this is a chunk of Gavel.js output corresponding to "output.body"
    validator: 'JsonExample',
    rawData: '...'
    results: []
  }
})

Note that the validation result chunk doesn't contain the real/expected values. That is most likely the reason the library's API has a separate dataReal and dataExpected. Imho this is a flaw, and we can leverage it in the unified Gavel validation result structure to also simplify various reporters.

According to the library's source code it doesn't really work without gavel. Sure, it will use fallback values for converters, but the output will miss pointers and other useful data Gavel result contains. If you define "work" as in "works as designed", then no, I wouldn't say so.

Can I pass both data* and gavelResult options? What would be the output?

Yes, in fact you should. The library uses gavelResult.validator property of the validation result of an individual field to pick a proper "converter": https://github.com/apiaryio/gavel2html/blob/dd4d441efa04d948ba2009a83f70910ba3871c51/src/gavel2html.coffee#L86-L101

When you don't pass the gavelResult object, the text converter will be used. Since data* options are mandatory, I will reason about the library's output from the point of optional gavelResult.

If gavelResult is provided, the output of the library will contain:

What the usePointers means?

This option is used to determine the source of errors in json-result-converter.coffee: https://github.com/apiaryio/gavel2html/blob/dd4d441efa04d948ba2009a83f70910ba3871c51/src/json-result-converter.coffee#L14-L17

In case usePointers: true the library will use pointers from gavelResult.results[n].pointer, otherwise from gavelResult.rawData[n] (quoting source code, I always assumed rawData is a string).

What structure should gavelResult have?

As mention before, the library expects a chunk of the Gavel.js output. So the gavelResult parameter should look like:

type gavelResult = {
  validator: 'JsonExample' | 'TextDiff' | AnyOtherValidator
  realType: string
  expectedType: string
  rawData: string // but, apparently, Amanda returns object
  result: ValidationError[]
}

Note that I'm quoting the code from the previous implementation of Gavel.js according on the gavel-spec. Once the next proposal is approved, things may change around.

What do following options mean and what is their behavior?

Let's try to break down each mentioned option separately.

wrapWith

Used in the base Converter class:

https://github.com/apiaryio/gavel2html/blob/dd4d441efa04d948ba2009a83f70910ba3871c51/src/converter.coffee#L47-L48

Seems to be used as a string to wrap the library's output. I understand its behavior as follows:

Given library's original output is "foo"
And "wrapWith" option is set to "The ouput: ##data end"
Then the library's final output will be:
"""
The output: foo end
"""

startTag / endTag / missingStartTag / addedStartTag / changedStartTag

All are used during the output of a result fragment: https://github.com/apiaryio/gavel2html/blob/dd4d441efa04d948ba2009a83f70910ba3871c51/src/converter.coffee#L71-L96

comments

A boolean flag indicating that the library's output should also include comments.

commentStartTag / commentEndTag

String wrappers around each comment if comment option is set to true:

https://github.com/apiaryio/gavel2html/blob/dd4d441efa04d948ba2009a83f70910ba3871c51/src/converter.coffee#L91-L94

identString

I think is meant to be iNdentString. Its value is used as a custom string for indentation during the output of JSON. https://github.com/apiaryio/gavel2html/blob/dd4d441efa04d948ba2009a83f70910ba3871c51/src/json-result-converter.coffee#L182-L186

What is exactly the output of this library? What characteristics it should possess?

You can find that in tests' fixtures: https://github.com/apiaryio/gavel2html/blob/dd4d441efa04d948ba2009a83f70910ba3871c51/test/fixtures/gavel2html-pointers.coffee

I believe the library produces an HTML string then is later injected into any context (documentation, transactions log, etc.).

This should give anybody a quick overview about the questions asked, and it sure helped me to understand the library's internals in a better way. Redesign proposal and more technical details should follow in the whitepaper.

artem-zakharchenko commented 5 years ago

I suggest to write a documentation after we rewrite gavel2html and I suggest to write it using Markdown and any doc generator available (or even in-repository, depending on scale).

honzajavorek commented 5 years ago

I'd like to award you with an Apiary Champollion Prize 🎖