Documentation html fix #1412

wants to merge 4 commits into


None yet

2 participants

andyli commented Mar 31, 2013

Here is a number of html fixes for the html files. I've checked all the html files in doc folder, and they will be valid html once this pull request is merged.

In fact, I'm trying to make the doc more machine readable, such that it would be easier to generate extern files for haxe or declaration files for TypeScript.

My plan is to convert things like:

<dt id="getLineNumber"><code>doc.getLineNumber(handle) → integer</code></dt>

into something similar to:

<dt id="getLineNumber" class="method">
  <span class="owner">doc</span>.<span class="name">getLineNumber</span>(<span class="argument" data-type="lineHandle">handle</span>) → <span class="return" data-type="integer">integer</span>

Do you have any opinion? I will make another pull request if you think it is good to go.

marijnh commented Apr 2, 2013

Thanks for fixing these! Merged as 01c0c77

Since I'm editing the HTML docs by hand, I am not really interested in having a bunch of verbose cruft like the markup you propose in it. You could parse the type descriptions quite well without adding all these spans -- they already follow a logic. This logic isn't always consistently followed at the moment, but I'd be open to pull requests that fix inconsistencies.

@marijnh marijnh closed this Apr 2, 2013
@andyli andyli deleted the andyli:doc-fix branch Apr 2, 2013
andyli commented Apr 2, 2013

Alright! What about standardizing the notation to be name:type? Name may be method name, property name or argument name in a method?

<dt id="getLineNumber"><code>doc.getLineNumber(handle: lineHandle): integer</code></dt>
<dt id="option_mode"><code>mode: string|object</code></dt>
marijnh commented Apr 3, 2013

I could live with that. Though saying that something is an 'object' is not going to be all that helpful. Maybe prefer a {foo: number, bar: ...} notation for simple objects, and use names for bigger ones (Doc, TextMarker)?

andyli commented Apr 3, 2013

Sounds good to me. I will work out a pull request :)

@andyli andyli referenced this pull request Apr 3, 2013

Doc format #1420

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment