IDL is the best source of the protocol information as of today. We should gen some docs out of it. Patch to follow, it generates something like: https://sites.google.com/site/webinspectorprotocol/
Created attachment 83092 [details] Patch
Comment on attachment 83092 [details] Patch View in context: https://bugs.webkit.org/attachment.cgi?id=83092&action=review > Source/WebCore/inspector/CodeGeneratorInspector.pm:528 > + push(@lines, " seq: number,"); should be <number> for consistency
Comment on attachment 83092 [details] Patch View in context: https://bugs.webkit.org/attachment.cgi?id=83092&action=review > Source/WebCore/inspector/CodeGeneratorInspector.pm:394 > +{ > + my $interface = shift; > + my $function = shift; > + > + my $functionName = $function->signature->name; > + my $domain = $interface->name; > + > + my @argsFiltered = grep($_->direction eq "out", @{$function->parameters}); > + > + my @lines; > + push(@lines, "<h4>" . $interface->name . "." . ${functionName} . "</h4>"); > + my $doc = $function->signature->extendedAttributes->{"doc"}; > + if ($doc) { > + push(@lines, $doc); > + } > + > + push(@lines, "<pre style='background: lightGrey; padding: 10px'>"); > + push(@lines, "{"); > + push(@lines, " seq: <number>,"); > + push(@lines, " type: \"event\","); > + push(@lines, " domain: \"$domain\","); > + if (scalar(@argsFiltered)) { > + push(@lines, " event: \"${functionName}\","); > + push(@lines, " data: {"); > + my @parameters; > + foreach my $parameter (@argsFiltered) { > + push(@parameters, " " . parameterDocLine($parameter)); > + } > + push(@lines, join(",\n", @parameters)); > + push(@lines, " }"); > + } else { > + push(@lines, " event: \"${functionName}\""); > + } > + push(@lines, "}"); > + push(@lines, "</pre>"); > + push(@documentationLines, @lines); > +} Please use inline text. It is significantly increasing readability. > Source/WebCore/inspector/CodeGeneratorInspector.pm:546 > + ditto
> > +} > > Please use inline text. It is significantly increasing readability. > > > Source/WebCore/inspector/CodeGeneratorInspector.pm:546 > > + > > ditto I tried that, but it made readability worse. Reason is that there are several conditions / loops that don't work well in combination with text chunks.
I generate "protocol docs" for weine as well - I have some of my own IDL as well as (obviously) reuse Inspector.idl. Rather than generate HTML, I generate JSON. I then have some JS code which generates HTML for the protocol doc. I reuse the same JSON in weinre as well - to generate proxies, etc. Current version, which I think matches the current IDL, is here: https://github.com/pmuellr/weinre/blob/develop/weinre.build/scripts/simple-idl2json.py
(In reply to comment #5) > I generate "protocol docs" for weine as well - I have some of my own IDL as well as (obviously) reuse Inspector.idl. Rather than generate HTML, I generate JSON. I then have some JS code which generates HTML for the protocol doc. I reuse the same JSON in weinre as well - to generate proxies, etc. > > Current version, which I think matches the current IDL, is here: > > https://github.com/pmuellr/weinre/blob/develop/weinre.build/scripts/simple-idl2json.py IDL is extremely limited in terms of markup for documentation generation. I'd much rather have JSON as a source for both generated code and the documentation. We only use IDL for historical reasons + IDLParser is a part of the build on all ports. If we figure out how to run JavaScript in the build, we will be able to use JSON source.
Comment on attachment 83092 [details] Patch View in context: https://bugs.webkit.org/attachment.cgi?id=83092&action=review >> Source/WebCore/inspector/CodeGeneratorInspector.pm:394 >> +} > > Please use inline text. It is significantly increasing readability. I second this comment. > Source/WebCore/inspector/CodeGeneratorInspector.pm:521 > + push(@lines, " command: \"${functionName}\""); This line can be pulled out of the if block.
Committed r79204: <http://trac.webkit.org/changeset/79204>
(In reply to comment #6) > IDL is extremely limited in terms of markup for documentation > generation. I'd much rather have JSON as a source for both > generated code and the documentation. We only use IDL for > historical reasons + IDLParser is a part of the build on all ports. I'm somewhat surprised to find that I actually like the IDL format. It's fairly concise, and turns out to be easy to parse. I especially like the trick of denoting call back parms as "out" parameters. Although I love JSON as a transportable data structure format, I really dislike writing it, and even reading it is kinda distasteful (this will change when there's a nice JSON viewer in all my "IDEs"). But it wouldn't be the end of the world for me if we switched to JSON. > If we figure out how to run JavaScript in the build, we will be > able to use JSON source. Well, WebKit nightlies build "jsc" (or they used to, or they can). Perhaps v8-based builds could be convinced to build a similar CLI, and we could parameterize the name of the executable. But really, a lot of languages can read JSON. Can't remember which version of Python shipped JSON built-in, or the lowest level of Python the night build requires. But it turns out, for Python, JSON structures are also legal Python literals, so you can just eval() them anyway. There's no reason to wait for a JavaScript interpreter if you want to switch from IDL to JSON. And if you're writing something new, I vote for Python over Perl.