search

bblfsh / documentation

Babelfish documentation (GitBook)
https://docs.sourced.tech/babelfish
Creative Commons Attribution Share Alike 4.0 International
41 stars 30 forks source link

Document DriverHost API (gRPC v2) #255

Closed dennwc closed 5 years ago

dennwc commented 5 years ago

We made a new Supported Languages API available in the gRPC protocol v2 and changed a few fields in the process. We should update docs to reflect this change.

bzz commented 5 years ago

I suggest we also add a new column to the https://doc.bblf.sh/languages.html with the list of supported aliases - that would allow users to avoid possible confusion on figuring out which languages are supported by which drivers.

dennwc commented 5 years ago

Mentioning aliases makes sense, although I'm wondering what is the use case for the end user? The driver either parses the file, or it's not. In the last case, we will get a new issue and will fix it by adding a new alias.

I don't think it's a bad idea, just want to save some space in the languages table :)

creachadair commented 5 years ago

I don't think it's a bad idea, just want to save some space in the languages table :)

Since I think not too many languages have aliases yet, we could maybe put a footnote in the table for each of the ones that do, listing the aliases. That way it'd still be close by to the table but not require a long column.

bzz commented 5 years ago

Mentioning aliases makes sense, although I'm wondering what is the use case for the end user?

for me, the only use case is to inform the user, in order to prevent people from hard-coding the aliases and adding them on their side, assuming that otherwise bblfshd will not be able to parse it. Here is an example.

dennwc commented 5 years ago

Oh, right, you mean to raise the awareness. OK, let me add the aliases then.

dennwc commented 5 years ago

To give a bit more context here, the issue is about resolving the FIXME comment in this file.

We should properly document all DriverHost methods and explain the difference between v1 and v2 methods (e.g. aliases, some fields missing, etc).

Later we will need to document the Parse API as well. Most of it is already done in https://github.com/bblfsh/documentation/pull/251, we only need to add a short description and reference that document. Probably deserves a separate issue.

kuba-- commented 5 years ago

Can we close it (@dennwc) ?