Extensions Docs Server: Proper $ref handling

Extensions Docs Server: Proper $ref handling

If an API has a $ref type to another file, it is now displayed with the prefix
of the API it is a ref to. For example if Tabs references Windows, the ref will
be windows.Window, but if Tabs references Tab, the ref will be just Tab.

Also, $refs are handled in descriptions.

BUG=131095
Committed: https://src.chromium.org/viewvc/chrome?view=rev&revision=149001

[cduvall, 2012-07-26 00:07:54]

Some clean up of the $ref handling.

[not at google - send to devlin, 2012-07-26 03:12:27]

Test?

http://codereview.chromium.org/10826024/diff/2001/chrome/common/extensions/do...
File chrome/common/extensions/docs/server2/handlebar_dict_generator.py (right):

http://codereview.chromium.org/10826024/diff/2001/chrome/common/extensions/do...
chrome/common/extensions/docs/server2/handlebar_dict_generator.py:26: type_name
= ref_type[namespace_name + '.':]
is this supposed to be len(namespace_name + '.') ?

http://codereview.chromium.org/10826024/diff/2001/chrome/common/extensions/do...
chrome/common/extensions/docs/server2/handlebar_dict_generator.py:56: def
_ReplaceRefsInDescription(self, description):
function needs -2 indentation

http://codereview.chromium.org/10826024/diff/2001/chrome/common/extensions/do...
chrome/common/extensions/docs/server2/handlebar_dict_generator.py:59: refs =
description.split('$ref:')
This is awesome. We should convert all those
chrome.{extension,runtime}.lastError references to be
$ref:chrome.runtime.lastError in all the docs.

Note that it looks like the current documentation system doesn't do this, so,
this is super useful.

http://codereview.chromium.org/10826024/diff/2001/chrome/common/extensions/do...
chrome/common/extensions/docs/server2/handlebar_dict_generator.py:61: for ref in
refs[1:]:
I don't think this algorithm works if the description starts with "$ref:".

http://codereview.chromium.org/10826024/diff/2001/chrome/common/extensions/do...
chrome/common/extensions/docs/server2/handlebar_dict_generator.py:65:
ref_dict['text'] + '</a> ' + rest)
use a format string?

also, tip: += is inefficient in python. You should form an array of parts then
use return ''.join(formatted_description) at the end.

http://codereview.chromium.org/10826024/diff/2001/chrome/common/extensions/do...
chrome/common/extensions/docs/server2/handlebar_dict_generator.py:83:
'description': type_.description,
run *all* descriptions of through ReplaceRefsInDescription? Perhaps call it
FormatDescription?

http://codereview.chromium.org/10826024/diff/2001/chrome/common/extensions/do...
File
chrome/common/extensions/docs/server2/test_data/test_json/expected_test_file.json
(left):

http://codereview.chromium.org/10826024/diff/2001/chrome/common/extensions/do...
chrome/common/extensions/docs/server2/test_data/test_json/expected_test_file.json:103:
],
oh wow how did all of this happen...

[cduvall, 2012-07-26 17:57:44]

http://codereview.chromium.org/10826024/diff/2001/chrome/common/extensions/do...
File chrome/common/extensions/docs/server2/handlebar_dict_generator.py (right):

http://codereview.chromium.org/10826024/diff/2001/chrome/common/extensions/do...
chrome/common/extensions/docs/server2/handlebar_dict_generator.py:26: type_name
= ref_type[namespace_name + '.':]
On 2012/07/26 03:12:27, kalman wrote:
> is this supposed to be len(namespace_name + '.') ?

Done.

http://codereview.chromium.org/10826024/diff/2001/chrome/common/extensions/do...
chrome/common/extensions/docs/server2/handlebar_dict_generator.py:56: def
_ReplaceRefsInDescription(self, description):
On 2012/07/26 03:12:27, kalman wrote:
> function needs -2 indentation

Done.

http://codereview.chromium.org/10826024/diff/2001/chrome/common/extensions/do...
chrome/common/extensions/docs/server2/handlebar_dict_generator.py:59: refs =
description.split('$ref:')
On 2012/07/26 03:12:27, kalman wrote:
> This is awesome. We should convert all those
> chrome.{extension,runtime}.lastError references to be
> $ref:chrome.runtime.lastError in all the docs.
> 
> Note that it looks like the current documentation system doesn't do this, so,
> this is super useful.

I shouldn't do this now because it will break the old docs right?

http://codereview.chromium.org/10826024/diff/2001/chrome/common/extensions/do...
chrome/common/extensions/docs/server2/handlebar_dict_generator.py:61: for ref in
refs[1:]:
On 2012/07/26 03:12:27, kalman wrote:
> I don't think this algorithm works if the description starts with "$ref:".

I think it does:

'$ref:Reffy is cool'.split('$ref:')
['', 'Reffy is cool']

http://codereview.chromium.org/10826024/diff/2001/chrome/common/extensions/do...
chrome/common/extensions/docs/server2/handlebar_dict_generator.py:65:
ref_dict['text'] + '</a> ' + rest)
On 2012/07/26 03:12:27, kalman wrote:
> use a format string?
> 
> also, tip: += is inefficient in python. You should form an array of parts then
> use return ''.join(formatted_description) at the end.

Done.

http://codereview.chromium.org/10826024/diff/2001/chrome/common/extensions/do...
chrome/common/extensions/docs/server2/handlebar_dict_generator.py:83:
'description': type_.description,
On 2012/07/26 03:12:27, kalman wrote:
> run *all* descriptions of through ReplaceRefsInDescription? Perhaps call it
> FormatDescription?

Done.

[not at google - send to devlin, 2012-07-30 08:04:34]

lgtm

http://codereview.chromium.org/10826024/diff/2001/chrome/common/extensions/do...
File chrome/common/extensions/docs/server2/handlebar_dict_generator.py (right):

http://codereview.chromium.org/10826024/diff/2001/chrome/common/extensions/do...
chrome/common/extensions/docs/server2/handlebar_dict_generator.py:59: refs =
description.split('$ref:')
On 2012/07/26 17:57:44, cduvall wrote:
> On 2012/07/26 03:12:27, kalman wrote:
> > This is awesome. We should convert all those
> > chrome.{extension,runtime}.lastError references to be
> > $ref:chrome.runtime.lastError in all the docs.
> > 
> > Note that it looks like the current documentation system doesn't do this,
so,
> > this is super useful.
> 
> I shouldn't do this now because it will break the old docs right?

Actually it looks like it _does_ deal with $ref:

http://src.chromium.org/svn/trunk/src/chrome/common/extensions/docs/js/api_pa...
(search for $ref, about 2/3 of the way down).

So yeah, you could do that for lastError. Though in a follow up (and check that
it doesn't break the existing docs).