Add some documentation for ProtoBufSchemaGenerator in formats.md

[justinhj]

Hi, this is a PR for #1778

I've added a bit of documentation in formats.md about the ProtoBufSchemaGenerator. Just enough to help the interested party see that it exists, an example and a link to the code.

If you think it will be useful I'll be happy to make any requested changes.

It is targeted at master since it is documentation only, but it looks like it will cleanly merge with dev if you prefer.

BTW Knit fails with the following, I'm not sure why.

> Task :knit FAILED
ERROR: /Users/justin.heyes-jones/projects/kotlinx.serialization/docs/formats.md: 486: Previous test was not emitted with TEST

[sandwwraith]

your language includes

Something is missing before 'includes', at least a comma

input stream. When using

Two spaces instead of one

[justinhj]

Thanks I'm sure I proof read it multiple times but then committed total nonsense.

[sandwwraith]

Fortunately, you can use SOMETHIING to output the ".proto" representation of your messages.

SOMETHING is missing

[sandwwraith]

Knit uses several magic lines, and

> You can get the full code [here](../guide/example/example-formats-07.kt).

is one of them you should insert here. Don't worry, number of example would be automatically updated by a knit task.

[sandwwraith]

Test output should be finished with <!--- TEST --> knit directive

[sandwwraith]

Have you re-run knit? It looks like the commit should also have generated example files, since their numeration got updated

[justinhj]

Have you re-run knit? It looks like the commit should also have generated example files, since their numeration got updated

I'm sorry I missed that step. I have run it now and updated the PR.

[sandwwraith]

Your example should be separate compilable unit:

e: /opt/buildAgent/work/b2fef8360e1bcf3d/guide/example/example-formats-08.kt: (13, 1): Expecting a top level declaration
e: /opt/buildAgent/work/b2fef8360e1bcf3d/guide/example/example-formats-08.kt: (13, 8): Expecting a top level declaration
e: /opt/buildAgent/work/b2fef8360e1bcf3d/guide/example/example-formats-08.kt: (13, 9): Expecting a top level declaration
e: /opt/buildAgent/work/b2fef8360e1bcf3d/guide/example/example-formats-08.kt: (13, 16): Expecting a top level declaration
e: /opt/buildAgent/work/b2fef8360e1bcf3d/guide/example/example-formats-08.kt: (4, 2): Cannot access 'Serializable': it is internal in 'kotlin.io'
e: /opt/buildAgent/work/b2fef8360e1bcf3d/guide/example/example-formats-08.kt: (4, 2): This class does not have a constructor
e: /opt/buildAgent/work/b2fef8360e1bcf3d/guide/example/example-formats-08.kt: (11, 37): Unresolved reference: serializer
e: /opt/buildAgent/work/b2fef8360e1bcf3d/guide/example/example-formats-08.kt: (12, 15): Unresolved reference: ProtoBufSchemaGenerator
e: /opt/buildAgent/work/b2fef8360e1bcf3d/guide/test/FormatsTest.kt: (64, 70): Unresolved reference: main

I suggest adding import kotlinx.serialization.* and other required imports and wrapping vals/println into fun main(). Then update Knit and run ./gradlew :guide:test knitCheck to check that everything is ok

[justinhj]

./gradlew :guide:test knitCheck

Thanks for your patience! I wasn't familiar with what knit did. Have now fixed the knit related issues.

[sandwwraith]

Thanks for all your efforts and time!