jbalsas / apify Goto Github PK

In the nav, there seems to be an extra "Modules" folder at the top that doesn't go anywhere. Also, on the main page, there's another "Modules" header that seems redundant. It would make sense to me to just remove these entirely.

Most angle brackets in types are encoded, but I found some that are not. For example, look in Menus.js Variables section at contextMenuMap and menuItemMap. Markup generated like:

                <dl>
                    <dt>Type</dt>
                      <dd>Object.<string, ContextMenu></dd>
                </dl>

Renders as "Object."

This should be:

                <dl>
                    <dt>Type</dt>
                      <dd>Object.&lt;string, ContextMenu&gt;</dd>
                </dl>

I think it would look nicer if the title were aligned over the content, and the nav took up the entire left column.

Currently, the code wraps. It might be nice to have a checkbox to turn that off (i.e. scroll instead).

According to http://usejsdoc.org/about-getting-started.html:

"JSDoc comments should generally be placed immediately before the code being documented. It must start with a /** sequence in order to be recognized by the JSDoc parser. Comments beginning with /*, /***, or more than 3 stars will be ignored. This is a feature to allow you to suppress parsing of comment blocks. "

For example:

/*global define, $, brackets, window */
define(function (require, exports, module) {

Version 10.2 is available and has many improvements.

https://github.com/twitter/typeahead.js/blob/master/CHANGELOG.md

I'm seeing this path being generated:

<a href="../modules/src/command&#x2F;Menus.html">Menus</a>

Although it seems to work, I don't think / should be used. Should simply be:

<a href="../modules/src/command/Menus.html">Menus</a>

Since only the content is scrollable, that extra scrollbar isn't needed and is easy to remove. The problem is that in the body the padding top and bottom are equal to 110px together but when calculating the height using calc, it only subtracts 95px. So we need to increase one or decrease the other or both so that the content fits in 1 screen.

If I scroll down and select a file on the left, the file contents are displayed in the pane on the right. The pane is scrolled to the top when file is first opened (as it should), but file list is scrolled with it.

Would be nice if file list scrolled separately from the pane.

these are pretty tough but here is a simple example of a type:

/**
 * A number, or a string containing a number.
 * @typedef {(number|string)} NumberLike
 */

Here's a radical example (real-use):

  /**
     * Called to get the full path of the view
     * @callback getFullPathCallBack
     * @return {!string} fullPath of the view
     */

    /**
     * Called to get the File object of the view
     * @callback getFileCallBack
     * @return {!File} File object that belongs to the view
     */

    /**
     * Called to change the show or hide the view
     * @callback setVisibleCallBack
     * @param {!boolean} true to show the view, false to hide it
     */

    /**
     * Called to let the view know that it needs to be resized and redrawn
     * @callback resizeToFitCallBack
     * @param {Object=} hint - hint data on how to redraw the view (can be null)
     */

    /**
     * Called to destroy the view object so that it can remove its DOM node from the pane
     * @callback destroyCallBack
     */

    /**
     * Called to determine if the view or child of the view has focus
     * @callback hasFocusCallBack
     * @return {!boolean} true if has focus, false otherwise
     */

    /**
     * Called to inform the view to give focus to its DOM element
     * @callback focusCallBack
     */

    /**
     * Called to get the view's scroll state so that it can be cached and restored later
     * view providers can return any data necessary to restore the scroll position from the cached data
     * @callback getScrollPosCallback
     * @return {*}
     */

    /**
     * Called to restore the scrollPane state and adjust it with a given height delta
     * @callback adjustScrollPosCallBack
     * @param {*} scrollPos - the data cached when getScrollPos was called
     * @param {!number} heightDelta - the height to add to the scroll pos data
     */

    /**
     * Called when a view is moved from one pane to another 
     * @callback switchContainersCallBack
     * @param {jQuery} $container - the new container for the view to move its DOM element in to
     */

    /**
     * Called to get the owning container of a view
     * @callback getContainerCallBack
     * @return {jQuery} the container for the view
     */

    /**
     * View interface
     * @typedef {Object} View
     * @property {getFullPathCallBack} getFullPath 
     * @property {getFileCallBack} getFile 
     * @property {setVisibleCallBack} setVisible 
     * @property {resizeToFitCallBack} resizeToFit 
     * @property {destroyCallBack} destroy 
     * @property {hasFocusCallBack} hasFocus 
     * @property {hasFocusCallBack} childHasFocus 
     * @property {focusCallBack} focus 
     * @property {getScrollPosCallback} getScrollPos 
     * @property {adjustScrollPosCallBack} adjustScrollPos 
     * @property {switchContainersCallBack} switchContainers 
     * @property {getContainerCallBack} getContainer
     */

The modules in src/extensions folder should be excluded (similar to src/nls modules).

The apify command-line program fails when I use . as the input source directory, but it works fine when I use other paths to refer to the same directory, like ../my-project or an absolute path. Here's the stack trace:

$ apify -s . -o docs

/usr/local/lib/node_modules/apify/lib/utils/Workspace.js:57
                    docPath: pathUtils.normalize(data[1].replace(src, ""))
                                                         ^
TypeError: Cannot call method 'replace' of undefined
    at /usr/local/lib/node_modules/apify/lib/utils/Workspace.js:57:58
    at Array.map (native)
    at /usr/local/lib/node_modules/apify/lib/utils/Workspace.js:51:16
    at /usr/local/lib/node_modules/apify/node_modules/find/index.js:147:26
    at Chain.onend (/usr/local/lib/node_modules/apify/node_modules/find/index.js:92:26)
    at Chain.next (/usr/local/lib/node_modules/apify/node_modules/find/node_modules/traverse-chain/index.js:70:10)
    at Chain.onend (/usr/local/lib/node_modules/apify/node_modules/find/index.js:92:17)
    at Chain.next (/usr/local/lib/node_modules/apify/node_modules/find/node_modules/traverse-chain/index.js:70:10)
    at /usr/local/lib/node_modules/apify/node_modules/find/index.js:79:23
    at Object.oncomplete (fs.js:107:15)

Currently, we support only a few templates, and they keep growing as we keep adding new features. In addition, because of our lack of support, we are copy/pasting markup in several places every time we make a change.

We need to refactor the templates to make them simple, reusable and configurable.

Brackets uses the @deprecated tag to mark deprecated APIs in many places.

 /**
     * localized pane titles 
     * @type {Object.{FIRST_PANE|SECOND_PANE, <VERTICAL.string, HORIZONTAL.string}}}
     *  Localized string for first and second panes in the current orientation.  
     * @see {@link getPaneTitle()} for more information
     * @private
     */
   var _paneTitles  = {
    };

generates a link to getPaneTitle() (which is a valid API) but clicking on it does nothing. It should take you to the function getPaneTitle

In the nav, subfolders are listed using dot notation (e.g. "LiveDevelopment.Agents"). That doesn't really make sense for JS, which doesn't use Java-style package notation.

Currently, module descriptions are not being processed for markdown, when they should

/**
* id of the pane
* @type {!string}
* @readonly
*/
Pane.prototype.id = null;

==>

In Editor.js, Class Editor, Method convertToLineSelections the Returns value is so long that it's truncated.

Would be nice if this were logically broken into separate lines, but that's not easy to do for all cases (maybe that should be done manually in code comment). But, for other cases, maybe page should be overflow:auto to get scroll bars.

@param tags that separate name and description with a hyphen show up with a hyphen in the doc

    /*
     * Pane Objects are constructed by the MainViewManager object when a Pane view is needed
     * @see {@link MainViewManager} for more information
     *
     * @constructor
     * @param {!string} id - The id to use to identify this pane
     * @param {!JQuery} $container - The parent $container to place the pane view
     */

Generate documentation that looks like this:

The hyphens add readability to the code and are recommended by usejsdoc.org for readability. It would be great if APIFY could remove them

It would be awesome to be able to link directly to the docs for a specific function by adding a fragment (#apiName) to the end of the URL. Right now, you can link to the module but nothing more specific than that...

Currently, all the pages have no <title>, so the browser tab just shows the URL. Often all there's room to show is the generic start of the URL -- e.g. "http://brackets.io/docs/curr" -- so you can't tell which module/class/etc. the tab is actually showing.

Ideally, there'd be a configurable overall title plus page-specific prefixes, so the page title would something like: "CommandManager - Brackets API docs."

Creating a general issue for listing of other files and folders to exclude:

• extensibility/node

When scanning through a function doc, the type labels really stand out - even more so than the parameter names and descriptions. I'm not sure they really deserve to be the most prominent thing on the page :) It might be good to have @larz0 take a pass at rebalancing the visual weight of the various elements (function names, parameter names, types, and descriptions).

Would be useful to have a Collapse All and Expand All as part of the tree UI. Right now the fact that all tree nodes are expanded by default is sufficient, but, if we retain the tree state per #4, having the ability to expand or collapse all nodes would be useful as well.

@jbalsas These are the notes from the e-mail conversation we had.

• Custom content with Resource Links
• Embed README.md or CONTRIBUTING.md?

What other resource links might be helpful?

• Annotating JavaScript for Closure Compiler
• Coding Conventions doc?
• How to Hack on Brackets wiki page?
• LICENSE.md?
• Wiki?
• Required repos: brackets-shell?
• Submodules: CodeMirror, jstree, etc.?
• Libraries: jQuery, LESS, etc.?

1. Indenting is inconsistent
2. Change from 4 to 2 space indenting to make it easier to fix # 1

http://brackets.io/docs/current/modules/command/Commands.html is basically blank. Ideally it would list all the constants that are exported.

This seems to be working for other modules, though -- e.g. Menus does include things like BEFORE in the output.

Maybe the difference is that in Commands, it's assigning literals directly to exports.FOO, while in Menus there's an intermediate var declaration?

Case 1: For this case from CommandManager.js:

    /**
     * Map of all registered global commands
     * @type Object.<commandID: string, Command>
     */

Type is truncated to: "Object.<commandID:". This may be related to #14

Case 2: For this case from Editor.js:

    /** @type {boolean}  Guard flag to prevent focus() reentrancy (via blur handlers), even across Editors */
    var _duringFocus = false;

@type doesn't seem to be parsed when comment is in a single line.

Per this discussion:
https://groups.google.com/forum/#!topic/brackets-dev/fRY3qE-cm3A

Among others, the Editor.getSpaceUnits() class method is not showing up in the documentation even though there are documentation comments available.

     /**
     * sorts the pane's view list 
     * @param {!string} paneId - id of the pane to sort, ALL_PANES or FOCUSED_PANE
     * @param {sortFunctionCallback} compareFn - callback to determine sort order (called on each item)
     * @see {@link Pane.sortViewList()} for more information
     * @see {@link https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Array/sort|Sort Array - MDN}
     */

Does not produce any "See Also" links.

Brackets wants to use the @example tag to show example uses of its APIs.

http://usejsdoc.org/tags-example.html

There are many functions in src/language/CSSUtils.js which is caused by an unescaped and unbalanced <style> tag:

    <em><p>Finds matching selectors in the <style> block of a single HTML file; adds them to 'resultSelectors'</p></em>

This causes the rest of the content genrated for this file to be hidden.

Class Methods in this format are not recognized:

    /**
     * @constructor
     * My class
     */
    function MyClass() {
    }

    MyClass.prototype = {
        /**
         * My method
         */
        myMethod: function () {
        }
    };

See all of the classes of preferences/PreferencesBase.js

On Windows, in the Dependencies section of the brackets.js file, if I click on “Menus”, the link is to:

file:///C:/Users/redmunds/dev/github/brackets/docs/modules/command/Menus.html

but the file is actually located at:

file:///C:/Users/redmunds/dev/github/brackets/docs/modules/src/command/Menus.html

Actually, the link is:

<a href="..\../modules/command&#x2F;Menus.html">Menus</a>

The backslash () path separator will only work on a Windows system, so that should be a forward slash. Also, the /src folder is missing.

Seems like link should be one of these:

<a href="command/Menus.html">Menus</a>
<a href="../modules/command/Menus.html">Menus</a>
<a href="../../src/modules/command/Menus.html">Menus</a>

Interesting that in the left sidebar, there is another link to same module that is correct.

The root folder looks a little funny with nothing next to it. Maybe it could be labelled with "/" or "[root]" or some such.

In project/ProjectManager.js the _dirFirst Variable is not listed. There may be others -- I didn't check exhaustively.

File LiveDevelopment/Documents/HTMLDocument.js is missing all of the Methods. They all (most?) have JSDoc comments, so I'm not sure why they are not in generated file.

The list of Dependencies for brackets.js is so long that it's hard to tell what's in the list. The modules in left side bar are arranged by folder, so ordering the list alphabetically would not be a duplication.

Would be helpful if the the module tree would remember which folders are expanded and collapsed as you jump from page to page and when you leave, then return to, the site.

Using the @extends tag causes all text after it to be dropped. It's ok that not all Google Closure Annotations are supported now, but unsupported tags should be handled gracefully.

Markdown formatting is supported in Descriptions, but not in @param, @return, etc. For example, this:

     * @return {$.Promise} 
     *     A promise that is resolved with three parameters:
     *          contents - string: the document's text
     *          timestamp - Date: the last time the document was changed on disk (might not be the same as the last time it was changed in memory)
     *          lineEndings - string: the original line endings of the file, one of the FileUtils.LINE_ENDINGS_* constants;
     *              will be null if checkLineEndings was false.
     *     or rejected with a filesystem error.

Is rendered as:

Returns:
$.Promise
A promise that is resolved with three parameters: contents - string: the document's text timestamp - Date: the last time the document was changed on disk (might not be the same as the last time it was changed in memory) lineEndings - string: the original line endings of the file, one of the FileUtils.LINE_ENDINGS_* constants; will be null if checkLineEndings was false. or rejected with a filesystem error.

There are 2 examples of this in Menus.js:

    var BEFORE           = "before",
        AFTER            = "after",
        FIRST            = "first",
        LAST             = "last",
        FIRST_IN_SECTION = "firstInSection",
        LAST_IN_SECTION  = "lastInSection";

Shows up as Variable BEFORE.

    var NO_ERROR           = 0,
        ERR_UNKNOWN        = 1,
        ERR_INVALID_PARAMS = 2,
        ERR_NOT_FOUND      = 3;

Shows up as Varaible NO_ERROR.

These private functions are not listed:

• _initTest()
• _onReady()

The first line of all code blocks seems to have lost it's indenting. This example is from command/Menus.js:

var BEFORE           = "before",
        AFTER            = "after",
        FIRST            = "first",
        LAST             = "last",
        FIRST_IN_SECTION = "firstInSection",
        LAST_IN_SECTION  = "lastInSection";

In templates/module.html I see this in several places in the markup:

    <pre class="code"><code>{{code}}</code></pre>

In general, <pre> is for block-level markup of code and <code> is for inline markup of code, so this is most likely redundant. Especially, since there is a "code" class applied as well.

Should probably remove inner <code> tag.

It's displayed for Class Methods, just not Functions

CSSUtils.js causes this markup to be generated:

    <em><p>Returns a context info object for the current CSS import rule</p></em>

<em> is inline text markup which should never contain block-level markup such as a <p> tag, so this should be:

    <p><em>Returns a context info object for the current CSS import rule</em></p>

FYI, since this causes the text for entire paragraph to be italic, it's more for presentation than emphasis, so it may be better to add a class on the <p> tag and define the presentation in CSS.

Might be nice to see a list of all JSON files in project, and also be able to see the data.

Smaller JSON files can just be shown as code, but larger JSON files (e.g. LiveDevelopment/Inspector/Inspector.json) could benefit from a collapsable tree structure format.

Other useful data that we may want to add is HTML Templates.

The list of exports for modules don't seem to be part of the API format. Seems like this is prominent enough to have it's own section with a link in API bar at top (with "Dependencies", "Variables", "Functions", "Classes").

Actually, they are displayed in the "Code" section of the last function in the file. For example, in Menus.js go to "Functions" section, then registerContextMenu click on "Show Code" and you'll see the list of exports at the end of the code.

Maybe we need an @export syntax for this