Re: RDP reference documentation

[Joe Walker]

(CC: dev-devel...@lists.mozilla.org)

I like https://wbamberg.github.io/rdp-reference/docs/index.html. Nice!

I think we should we have a more formal doc system for RDP. I'm not aware
of any problems if we extend protocolDescription to include doc strings.
But I think it's worth us proving that we can use it ourselves for new
stuff before we think about you putting effort into it!

Joe.

On Fri, Oct 2, 2015 at 9:08 PM William Bamberg <wbam...@mozilla.com> wrote:

> Hi Joe
>
> You reminded me of something I had a look at a while back (almost exactly
> a year ago), but which never progressed.
>
> I thought it would be useful to have reference docs for RDP, listing all
> the actors, the requests they accept and the responses you get from them.
>
> I think it's not practical to write and maintain all this by hand, but we
> could think about generating it. The RDP already has a
> "protocolDescription" message, and using that I had a go at generating some
> pages: https://wbamberg.github.io/rdp-reference/docs/index.html.
>
> This is a static dump, but we could imagine generating it dynamically
> using a GitHub commit hook or something.
>
> Of course, it doesn't include actual docs, but even just knowing which
> requests an actor supports, and what arguments it takes, seems like a
> useful thing.
>
> Back when I looked into this, I also filed a bug:
> https://bugzilla.mozilla.org/show_bug.cgi?id=1070270 to extend
> protocolDescription to include doc strings: many actors already have good
> in-source documentation, but if we included it in protocolDescription, then
> we could expose it in docs pages.
>
> (I might volunteer to do copy-pasting of in-source comments into
> protocolDescription field, if it were deemed to be a good idea.)
>
> There are problems: I think not all devtools support protocolDescription
> (IIRC I did something nasty with Valence to get a description for those
> actors). But even if it was incomplete, it might be worth doing.
>
> What do you think?
>
> Will
>
>
>
>

[Nick Fitzgerald]

The debugger-related subprotocol is pretty well documented (thanks, jimb!)
and there's some higher level concept documentation that is very good for
people who are just being introduced to the protocol (what is an actor?
what lifetimes are we dealing with? etc). Although, I think it doesn't get
kept up to date as much as it used to.

https://wiki.mozilla.org/Remote_Debugging_Protocol

+1 for doc strings for individual requests/notifications: they are closer
to the source, so easier to fix up if you happen to notice they're missing
or outdated.

Not sure if the broader concepts docs can fit into that framework (or
should even try to) though.

> _______________________________________________
> dev-developer-tools mailing list
> dev-devel...@lists.mozilla.org
> https://lists.mozilla.org/listinfo/dev-developer-tools
>

[James Long]

I'm for this, however we implement it, generating docs would work really
well for the RDP I think. It would stay much more up-to-date.

On Mon, Oct 5, 2015 at 10:54 AM, Nick Fitzgerald <nfitz...@mozilla.com>
wrote: