uniffi-rs Add support to document the bindings, copied from in-IDL documentation

Add support to document the bindings, copied from in-IDL documentation

Open jhugman opened this issue 3 years ago • 11 comments

Getting the foreign language devs closer to the documentation.

If the IDL parser gives us access to the comments, we should try hard to copy it over to the bindings.

┆Issue is synchronized with this Jira Task ┆Issue Number: UNIFFI-9

Aug 04 '20 18:08 jhugman

See also: https://github.com/mozilla/uniffi-rs/issues/43

Aug 04 '20 18:08 eoger

@eoger I'm wondering if this has been solved, as I see that it's been "closed as completed" in https://github.com/mozilla/application-services/issues/4254 and https://github.com/mozilla/application-services/issues/3436.

We've been using a sort of patch system where we apply a patch to the bindings file every time we build a new one, but most often not all hunks in the patch can be applied and much manual work has to be done. It's very error prone, and I don't like the idea of us poking around in the auto-generated bindings file too much. On the other hand, if we don't, we have no API docs we can generate in Dokka, nor do we get hints with auto-completion and the like. Would love to find a better, long-term solution to this.

Jun 15 '22 13:06 thunderbiscuit

I don't think this is done, and those other issues were probably closed as "completed" in error - I think the intent was to just not track them over there.

I also suspect that this is likely to never happen - afaik we can't get the comments out of the UDL, but more importantly, we are probably going to move away from UDL files entirely in favor of #1257, so it's unlikely we will spend much more effort improving UDL support unless strictly necessary.

Jun 16 '22 03:06 mhammond

Oh that's very exciting! I see some of that code has been merged to main so I assume it's passed the design phase and is moving full steam ahead? From reading the related issues/PR I see it might be possible to do partial migration; we'd be happy to be early testers of that. I'll keep an eye out for those changes.

Jun 16 '22 17:06 thunderbiscuit

Do you think its possible to squeeze in documentation to .udl files via attributes or something like that? It doesn't have to be pretty, just good enough to work until proc-macros are ready.

Mar 08 '23 08:03 arg0d

I'm sure many things are possible, but to be frank, this isn't something mozilla is going to prioritize in the short term.

Mar 08 '23 20:03 mhammond

I'm going to try and make a contribution on this. My current plan is to introduce a new extended attribute Attribute::Doc, and parse it for all nodes that desire documentation, e.g. Function, Enum, Error, Interface, Constructor, Method, Record. WebIDL parser supports multiline strings, so its possible to write multiline attributes. textwrap crate can be used to normalize indentation in multiline string, and to indent by desired level in generated bindings.

Sample 1

I have tested this, and it works. This version looks kind of weird tbh.

namespace testing {
  [Throws=ArithmeticError,
  Doc="
  Sub `b` from `a`.
  Return an error if
  `a` is less than `b`"]
  u64 sub(u64 a, u64 b);
}

Sample 2

I have tested this, and it works. I prefer this version the most. Notice that the closing "] is somehow parsed correctly, even in the presence of /// :thinking:.

namespace testing {
  [Throws=ArithmeticError,
  Doc="
  /// Sub `b` from `a`.
  /// Return an error if
  /// `a` is less than `b`"]
  u64 sub(u64 a, u64 b);
}

Sample 3

I haven't tested this. This version is verbose and hard to read.

namespace testing {
  [Throws=ArithmeticError,
  Doc="Sub `b` from `a`.",
  Doc="Return an error if",
  Doc="`a` is less than `b`"]
  u64 sub(u64 a, u64 b);
}

Mar 15 '23 12:03 arg0d

Hi, we've developed a documentation comments solution in our fork, see example.

But we've took alternative approach - doc comments are extracted from accompanying Rust code instead of .udl file - parsing Rust code proved much easier than modifying weedle parser to keep comments in AST (and we haven't considered using "Doc" attribute like you did).