dart-lang/api.dart.dev

Dart API docs

api.dart.dev's Issues

Several pages use an old jQuery version that has known security issues

Outdated library in api.dartlang.org/stable/1.20.1/dart-html/dart-html-library.html
https://code.jquery.com/jquery-2.1.4.min.js
Library: jquery
Version: 2.1.4.min

Outdated library in events.dartlang.org/2016/summit/
Library: jquery
Version: 2.2.4

We should update to jQuery 3 to resolve this.

fix redirects for older versions of dev and stable

Keyboard shortcuts for search

Up and down arrow don’t work in search. Hitting enter doesn’t work either. Also I think it’s missing ctrl+3 (cmd+3 on mac) shortcut for focusing on search box.
(feature request) search box + keyboard events: after you search and the completion shows some good results, it would be great if I could navigate to a query result using the keyboard. For example, use the up and down keys to highlight an option, and hit enter to select it.

Redirect not working as expected

A customer reported:

Going to https://api.dartlang.org/apidocs/channels/stable/dartdoc-viewer/dart:core.List does not redirect to https://api.dartlang.org/1.12.0/dart-core/List-class.html as we would expect.

The customer arrived at the link because that's how Chrome was auto-completing "dart list api" for him.

Actual: goes to the index of the docs.

Re-enable CORS

CORS was enabled at api.dartlang.org (see Dart issue 8404) to encourage mashups with our JSON docs. Some time in the last week, CORS was disabled. I assume it has to do with the new docgen or dartdoc-viewer, as the URL of the docs has also changed, from

https://api.dartlang.org/apidocs/channels/stable/docs/dart:async

to

https://api.dartlang.org/apidocs/channels/stable/dartdoc-viewer/dart:async

In any case, we should re-enable CORS.

CC @sethladd @alan-knight @ricowind

Initial page load on IE appears to hang the browser for 5-10 seconds

Even after items are rendered, there’s a long pause before the page becomes reactive.

Add a Search URL

The search box is backed by JS magic and I don't ever see it hit a URL to do the searching.
I'd like to add a search engine shortcut to chrome but I'd need to be able to build a query URL and I can't find a way to do that.

api.dartlang.org does not have a "certificate transparency" proof in its certificate

We need to have a certificate with certificate transparency at our next update or Chrome will put interstitals in accesses to api.dartlang.org.

Suggestion: Website footer version label lower height and dark theme request

Footer version label: 16px,20px padding is slightly extra IMO. Also causes distraction, I edited the padding to 5px seems less obstructive.
Dark site Appearence: I also want to suggest a non white background theme for the entire api site. This helps people with light sensitivity.

Multiple color schemes...

Would be nice to be able to switch to a "dark" mode without using plugins. Small stylish example:

body {
  background: #202020;
  color: #d0d0d0;
}

.sidebar {
  background: #606060;
}

.sidebar a {
  color: rgb(182, 182, 182);
}

section.summary h2,
.signature,
dd {
  color: rgb(190, 190, 190);  
}

code {
  background: #404040;
}

Merge new-dartdocs into master branch

1.12 is out, I think we can merge branches. Thanks!

Show return type on hover

It would be nice if you could hover over return types that are too long to be shown, or otherwise see the information. See, e.g. the variables "rules" on the page at http://jacobr.sea.corp.google.com:8000/web/out/index.html#!{"id":"serialization/Reader"}

regenerate and upload docs for 1.12.2

with newer version of dartdoc.

Abstract classes should list who implements them

Example: I search for Random in the search box. The abstract class Random is the first result, but of course I can't instantiate one, so it is not so useful. I need one I can instantiate.

/stable directs to a dev channel docs

If I go to https://new-dartdocs-dot-dartlang-api.appspot.com/stable , I'm redirected to https://new-dartdocs-dot-dartlang-api.appspot.com/1.12.0-dev.5.0/index.html

I would expect /stable to go to a stable release.

stack trace from server: http://api.dartlang.org/docs/releases

local variable 'path' referenced before assignment
Traceback (most recent call last):
  File "/python27_runtime/python27_lib/versions/third_party/webapp2-2.3/webapp2.py", line 1511, in __call__
    rv = self.handle_exception(request, response, e)
  File "/python27_runtime/python27_lib/versions/third_party/webapp2-2.3/webapp2.py", line 1505, in __call__
    rv = self.router.dispatch(request, response)
  File "/python27_runtime/python27_lib/versions/third_party/webapp2-2.3/webapp2.py", line 1253, in default_dispatcher
    return route.handler_adapter(request, response)
  File "/python27_runtime/python27_lib/versions/third_party/webapp2-2.3/webapp2.py", line 1077, in __call__
    return handler.dispatch()
  File "/python27_runtime/python27_lib/versions/third_party/webapp2-2.3/webapp2.py", line 547, in dispatch
    return self.handle_exception(e, self.app.debug)
  File "/python27_runtime/python27_lib/versions/third_party/webapp2-2.3/webapp2.py", line 545, in dispatch
    return method(*args, **kwargs)
  File "/base/data/home/apps/s~dartlang-api/releases-test.364427003867948283/scripts/redirector.py", line 80, in get
    path = self.resolve_doc_path()
  File "/base/data/home/apps/s~dartlang-api/releases-test.364427003867948283/scripts/redirector.py", line 75, in resolve_doc_path
    if path.endswith('/'):
UnboundLocalError: local variable 'path' referenced before assignment

Traceback (most recent call last):
  File "/python27_runtime/python27_lib/versions/1/google/appengine/runtime/wsgi.py", line 223, in Handle
    result = handler(dict(self._environ), self._StartResponse)
  File "/python27_runtime/python27_lib/versions/third_party/webapp2-2.3/webapp2.py", line 1519, in __call__
    response = self._internal_error(e)
  File "/python27_runtime/python27_lib/versions/third_party/webapp2-2.3/webapp2.py", line 1511, in __call__
    rv = self.handle_exception(request, response, e)
  File "/python27_runtime/python27_lib/versions/third_party/webapp2-2.3/webapp2.py", line 1505, in __call__
    rv = self.router.dispatch(request, response)
  File "/python27_runtime/python27_lib/versions/third_party/webapp2-2.3/webapp2.py", line 1253, in default_dispatcher
    return route.handler_adapter(request, response)
  File "/python27_runtime/python27_lib/versions/third_party/webapp2-2.3/webapp2.py", line 1077, in __call__
    return handler.dispatch()
  File "/python27_runtime/python27_lib/versions/third_party/webapp2-2.3/webapp2.py", line 547, in dispatch
    return self.handle_exception(e, self.app.debug)
  File "/python27_runtime/python27_lib/versions/third_party/webapp2-2.3/webapp2.py", line 545, in dispatch
    return method(*args, **kwargs)
  File "/base/data/home/apps/s~dartlang-api/releases-test.364427003867948283/scripts/redirector.py", line 80, in get
    path = self.resolve_doc_path()
  File "/base/data/home/apps/s~dartlang-api/releases-test.364427003867948283/scripts/redirector.py", line 75, in resolve_doc_path
    if path.endswith('/'):
UnboundLocalError: local variable 'path' referenced before assignment

Sitemap should be automatically added

And generated from a branch on Alan's machine. Generation should be integrated, and adding it to the site automated.

Hook up to webmaster tools

"Properties" link is broken

Clicking on the "Properties", "Constructors", "Methods", etc. links in the right-hand side grey box doesn't do anything.

Some legacy links are broken.

Some links used in stackoverflow or other forums are broken.

An example is:
http://api.dartlang.org/docs/releases/latest/intl/DateFormat.html

Please regenerate all docs with dartdoc 0.6.2

And re-upload.

Thanks!!

api.dartlang.org is not serving version 2.0.0-dev api docs

One problem is that server/scripts/redirector.py needs to check both the major and minor version number in the build_gcs_path function.

Checking everything else, that seems to be the only problem.

Commit latest changes

cc @keertip

More redirects not working

At some point, we supported http://api.dartlang.org/dart_core/Iterable.html

That should go to https://api.dartlang.org/1.12.0/dart-core/Iterable-class.html

Also, we had http://api.dartlang.org/dart_html.html

which should redirect to https://api.dartlang.org/1.12.0/dart-html/dart-html-library.html

Redirect old build number docs

We can write a redirect for api.dartlang.org/SOME_BUILD_NUMBER to api.dartlang.org/build/SOME_BUILD_NUMBER

cc @keertip is that correct?

Make version-agnostic URLs the default

[Copied from https://github.com/dart-lang/dartdoc/issues/1074.]

People are constantly linking to, say, https://api.dartlang.org/1.12.1/dart-core/Object-class.html when they should instead be linking to https://api.dartlang.org/stable/dart-core/Object-class.html (or maybe a shorter URL like https://api.dartlang.org/dart-core/Object-class.html).

We should make it easier to get a good permalink. This could be combined, somehow, with showing the current version and a way of switching to the stable/dev version of the docs.

Personally, I'd rather have the displayed URL be generic (https://api.dartlang.org/dart-core/Object-class.html) unless you choose a particular version.

An (extreme) example of this is in the AngularJS docs:

The docs for angular.bind are in https://docs.angularjs.org/api/ng/function/angular.bind. A dropdown at the upper left shows which build the docs reflect. If you want another build, you can choose it from the dropdown. For example, if you use v1.4.8, then the URL switches to https://code.angularjs.org/1.4.8/docs/api/ng/function/angular.bind. (It's difficult to get back to the real "latest", so ... not a perfect solution.)

To repeat: We should make it easy for people to do the right thing, which I believe is linking to the latest stable version of the docs. We should make it possible to link to other docs, with minimal effort on the linker's part.

[Feature] Add history

One thing I really love with ExtJs API docs is that each new doc page is opened in a new tab.

That way you can esaily switch between 2/3 classes without having to reload them. That something that is quite often use during develoment.

Would you consider adding this feature ?

Consider using --rel-canonical-prefix for doc builds

dartdoc now has a --rel-canonical-prefix option. We might consider using this when building the docs for api.dartlang.org

Specifically, we can use --rel-canonical-prefix=https://api.dartlang.org/stable

From dart-lang/dartdoc#912

Toggle for different versions of the SDK

I'd love to toggle between our different channels, such as bleeding_edge, trunk, and milestone branches.

Enable CORS for api.dartlang.org

We'd like CORS headers sent from api.dartlang.org.

See http://enable-cors.org/

Basically: Send Access-Control-Allow-Origin: * on every HEAD and GET.

Release agnostic links to API pages not working

For example, https://api.dartlang.org/stable/dart-io/Directory-class.html should take you to the latest stable page for the Directory class.

But it's not currently working.

We need this for the docs.

thx

Functionality not in the SDK, but provided by pub packages is not discoverable.

See e.g.: https://code.google.com/p/dart/issues/detail?id=20852

Exception thrown on legacy URL

Try going to https://api.dartlang.org/apidocs/channels/stable/dartdoc-viewer/dart-async.Zone

I see:

global name 'self' is not defined
Traceback (most recent call last):
  File "/base/data/home/runtimes/python27/python27_lib/versions/third_party/webapp2-2.3/webapp2.py", line 1511, in __call__
    rv = self.handle_exception(request, response, e)
  File "/base/data/home/runtimes/python27/python27_lib/versions/third_party/webapp2-2.3/webapp2.py", line 1505, in __call__
    rv = self.router.dispatch(request, response)
  File "/base/data/home/runtimes/python27/python27_lib/versions/third_party/webapp2-2.3/webapp2.py", line 1253, in default_dispatcher
    return route.handler_adapter(request, response)
  File "/base/data/home/runtimes/python27/python27_lib/versions/third_party/webapp2-2.3/webapp2.py", line 1077, in __call__
    return handler.dispatch()
  File "/base/data/home/runtimes/python27/python27_lib/versions/third_party/webapp2-2.3/webapp2.py", line 547, in dispatch
    return self.handle_exception(e, self.app.debug)
  File "/base/data/home/runtimes/python27/python27_lib/versions/third_party/webapp2-2.3/webapp2.py", line 545, in dispatch
    return method(*args, **kwargs)
  File "/base/data/home/runtimes/python27/python27_lib/versions/third_party/webapp2-2.3/webapp2.py", line 652, in get
    uri = func(self, *args, **kwargs)
  File "/base/data/home/apps/s~dartlang-api/even-moar-redirects.386919581618495439/scripts/redirector.py", line 292, in redir_name
    self.error(404)
NameError: global name 'self' is not defined

Traceback (most recent call last):
  File "/base/data/home/runtimes/python27/python27_lib/versions/1/google/appengine/runtime/wsgi.py", line 267, in Handle
    result = handler(dict(self._environ), self._StartResponse)
  File "/base/data/home/runtimes/python27/python27_lib/versions/third_party/webapp2-2.3/webapp2.py", line 1519, in __call__
    response = self._internal_error(e)
  File "/base/data/home/runtimes/python27/python27_lib/versions/third_party/webapp2-2.3/webapp2.py", line 1511, in __call__
    rv = self.handle_exception(request, response, e)
  File "/base/data/home/runtimes/python27/python27_lib/versions/third_party/webapp2-2.3/webapp2.py", line 1505, in __call__
    rv = self.router.dispatch(request, response)
  File "/base/data/home/runtimes/python27/python27_lib/versions/third_party/webapp2-2.3/webapp2.py", line 1253, in default_dispatcher
    return route.handler_adapter(request, response)
  File "/base/data/home/runtimes/python27/python27_lib/versions/third_party/webapp2-2.3/webapp2.py", line 1077, in __call__
    return handler.dispatch()
  File "/base/data/home/runtimes/python27/python27_lib/versions/third_party/webapp2-2.3/webapp2.py", line 547, in dispatch
    return self.handle_exception(e, self.app.debug)
  File "/base/data/home/runtimes/python27/python27_lib/versions/third_party/webapp2-2.3/webapp2.py", line 545, in dispatch
    return method(*args, **kwargs)
  File "/base/data/home/runtimes/python27/python27_lib/versions/third_party/webapp2-2.3/webapp2.py", line 652, in get
    uri = func(self, *args, **kwargs)
  File "/base/data/home/apps/s~dartlang-api/even-moar-redirects.386919581618495439/scripts/redirector.py", line 292, in redir_name
    self.error(404)
NameError: global name 'self' is not defined

Remove insertname.py from repo

No longer needed.

Deleting old docs

Hi,

We can delete the old build number docs, if not already deleted.

minor UI nit: extra pixel line?

I just noticed a minor thing in the UI on my chromebook. THis only shows up when the window is maximized vertically.

I can see a line, practically just a 1px width, between the top-banner and the sub-banner. Here is a screenshot:

Then, when scrolling down and you make the subbanner disappear, the pixel line is visible on the top, above the top-banner. See for example that in this screenshot some of the letters are visible behind the banner (between the grey bookmarks bar and the Dart SDK banner:

Version information: Google Chrome 46.0.2490.82 (Official Build) (64-bit)

Page is empty

When going to the address http://api.dartlang.org (redirects to https://api.dartlang.org/apidocs/channels/stable/dartdoc-viewer/home) the page only displays the text: Dart API Documentation.

Similar, when going to https://api.dartlang.org/apidocs/channels/stable/dartdoc-viewer/dart:html.Element displays: Dart API Documentation for dart:html.Element.

This behavior has been observed in Google Chrome (Version 43.0.2357.125 (64-bit)) on Ubuntu 15.04 and Google Chrome (Version 43.0.2357.124 m) on Windows 8.

References in markdown text appear as null

References in markdown to elements currently appear as 'null' (for example see library description of Future)

Update favicon

If you look at dart.dev, you can see that it has the new, less green logo. I think this site should use that new logo, too.

webmaster tools identified two 404s

http://api.dartlang.org/dom.html

and

http://api.dartlang.org/io/HttpServer.html

These should redirect to the correct location.

Inherited methods are not showing up in abstract classes.

Inherited methods are not showing up in abstract classes. E.g., String is not showing compareTo even if inherited is on.

HttpRequest catchError parameter type and error message

In the API docs for HttpRequest (https://api.dartlang.org/apidocs/channels/stable/dartdoc-viewer/dart:html.HttpRequest) is example and it has catchError part with parameter type "Error".

When I run the code and there is error (I am testing catchError part), I get:
"Exception: Uncaught Error: type '_XMLHttpRequestProgressEvent' is not a subtype of type 'Error' of 'error'."

Because the type of parameter is not "Error" but "_XMLHttpRequestProgressEvent".
The type "Error" should be removed from the example.

And also print(error.toString()); outputs as "Instance of '_XMLHttpRequestProgressEvent'"
Better would be to have there for example: print(error.target.responseText);

Display specific versions

Is there a way to display the docs for a different version (except for the LATEST) of the SDK in the browser?

Alternativ: is there a URL template to load index.json/library_list.json for selected versions?

Need a 404 page

Support Google Analytics

If you haven't already, please wire in Google Analytics to listen to the events like "display class", etc. You can treat those as Page Views. We can use events for other things like "opened a description for a method". This is really important, we shouldn't launch without analytics wired in. I'm happy to help you with this, too, but it'll take some JS interop (bloats the code size) or some creative uses of postMessage().
-Seth

How do I access older versions of the news with the new server?

Curious if I can access 1.11 with https://new-dartdocs-dot-dartlang-api.appspot.com ? If so, how?

Middle click doesn't open a new tab

Middle-click on Chrome opens a link in the same page. It should open a link in a new tab.

api.dartlang doesn't render correctly in Dartium

See the below.

Not adaptable to mobile phone

The current design doesn't scale down to a mobile phone.

Make it easy to switch between stable/beta/dev/be docs

We need an easy way for api.dartlang.org users to switch from the stable channel to the dev channel.

A simple way to do this would be to somehow stick a link on the homepage to https://api.dartlang.org/dev.

A more complex way to do this would be to have a version switcher on every page that tries to take you to the equivalent page in whichever version you select: stable or dev or be.

The sooner the better, since dartlang.org is already on Dart 2. (dartlang.org does take you to the dev version of API docs, but that doesn't help people who type in api.dartlang.org.)

I'll be happy to help with the words, but I couldn't figure out how to implement it myself.

/cc @kevmoo