Bug 54822 – Web Inspector: generate protocol documentation based on IDL.

• Component: Web Inspector (Deprecated)
• Status: RESOLVED FIXED

[Pavel Feldman]

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/

[Pavel Feldman]

Created attachment 83092 [details]
Patch

[Alexander Pavlov (apavlov)]

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

[Ilya Tikhonovsky]

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: &lt;number&gt;,");
> +    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

[Pavel Feldman]

> > +}
> 
> 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.

[Patrick Mueller]

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

[Pavel Feldman]

(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.

[Yury Semikhatsky]

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.

[Pavel Feldman]

Committed r79204: <http://trac.webkit.org/changeset/79204>

[Patrick Mueller]

(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.