Issue with documentation.build

[fourcolors]

Hey given this JS doc

/**
 * Copyright (c) 2015-present, Facebook, Inc.
 * All rights reserved.
 *
 * This source code is licensed under the BSD-style license found in the
 * LICENSE file in the root directory of this source tree. An additional grant
 * of patent rights can be found in the PATENTS file in the same directory.
 *
 * @providesModule Alert
 * @flow
 */
'use strict';

const AlertIOS = require('AlertIOS');
const NativeModules = require('NativeModules');
const Platform = require('Platform');

import type { AlertType, AlertButtonStyle } from 'AlertIOS';

type Buttons = Array<{
  text?: string,
  onPress?: ?Function,
  style?: AlertButtonStyle,
}>;

type Options = {
  cancelable?: ?boolean,
  onDismiss?: ?Function,
};

/**
 * Launches an alert dialog with the specified title and message.
 *
 * Optionally provide a list of buttons. Tapping any button will fire the
 * respective onPress callback and dismiss the alert. By default, the only
 * button will be an 'OK' button.
 *
 * This is an API that works both on iOS and Android and can show static
 * alerts. To show an alert that prompts the user to enter some information,
 * see `AlertIOS`; entering text in an alert is common on iOS only.
 *
 * ## iOS
 *
 * On iOS you can specify any number of buttons. Each button can optionally
 * specify a style, which is one of 'default', 'cancel' or 'destructive'.
 *
 * ## Android
 *
 * On Android at most three buttons can be specified. Android has a concept
 * of a neutral, negative and a positive button:
 *
 *   - If you specify one button, it will be the 'positive' one (such as 'OK')
 *   - Two buttons mean 'negative', 'positive' (such as 'Cancel', 'OK')
 *   - Three buttons mean 'neutral', 'negative', 'positive' (such as 'Later', 'Cancel', 'OK')
 *
 * By default alerts on Android can be dismissed by tapping outside of the alert
 * box. This event can be handled by providing an optional `options` parameter,
 * with an `onDismiss` callback property `{ onDismiss: () => {} }`.
 *
 * Alternatively, the dismissing behavior can be disabled altogether by providing
 * an optional `options` parameter with the `cancelable` property set to `false`
 * i.e. `{ cancelable: false }`
 *
 * Example usage:
 * ```
 * // Works on both iOS and Android
 * Alert.alert(
 *   'Alert Title',
 *   'My Alert Msg',
 *   [
 *     {text: 'Ask me later', onPress: () => console.log('Ask me later pressed')},
 *     {text: 'Cancel', onPress: () => console.log('Cancel Pressed'), style: 'cancel'},
 *     {text: 'OK', onPress: () => console.log('OK Pressed')},
 *   ],
 *   { cancelable: false }
 * )
 * ```
 */
class Alert {

  static alert(
    title: ?string,
    message?: ?string,
    buttons?: Buttons,
    options?: Options,
    type?: AlertType,
  ): void {
    if (Platform.OS === 'ios') {
      if (typeof type !== 'undefined') {
        console.warn('Alert.alert() with a 5th "type" parameter is deprecated and will be removed. Use AlertIOS.prompt() instead.');
        AlertIOS.alert(title, message, buttons, type);
        return;
      }
      AlertIOS.alert(title, message, buttons);
    } else if (Platform.OS === 'android') {
      AlertAndroid.alert(title, message, buttons, options);
    }
  }
}

/**
 * Wrapper around the Android native module.
 */
class AlertAndroid {

  static alert(
    title: ?string,
    message?: ?string,
    buttons?: Buttons,
    options?: Options,
  ): void {
    var config = {
      title: title || '',
      message: message || '',
    };

    if (options) {
      config = {...config, cancelable: options.cancelable};
    }
    // At most three buttons (neutral, negative, positive). Ignore rest.
    // The text 'OK' should be probably localized. iOS Alert does that in native.
    var validButtons: Buttons = buttons ? buttons.slice(0, 3) : [{text: 'OK'}];
    var buttonPositive = validButtons.pop();
    var buttonNegative = validButtons.pop();
    var buttonNeutral = validButtons.pop();
    if (buttonNeutral) {
      config = {...config, buttonNeutral: buttonNeutral.text || '' };
    }
    if (buttonNegative) {
      config = {...config, buttonNegative: buttonNegative.text || '' };
    }
    if (buttonPositive) {
      config = {...config, buttonPositive: buttonPositive.text || '' };
    }
    NativeModules.DialogManagerAndroid.showAlert(
      config,
      (errorMessage) => console.warn(errorMessage),
      (action, buttonKey) => {
        if (action === NativeModules.DialogManagerAndroid.buttonClicked) {
          if (buttonKey === NativeModules.DialogManagerAndroid.buttonNeutral) {
            buttonNeutral.onPress && buttonNeutral.onPress();
          } else if (buttonKey === NativeModules.DialogManagerAndroid.buttonNegative) {
            buttonNegative.onPress && buttonNegative.onPress();
          } else if (buttonKey === NativeModules.DialogManagerAndroid.buttonPositive) {
            buttonPositive.onPress && buttonPositive.onPress();
          }
        } else if (action === NativeModules.DialogManagerAndroid.dismissed) {
          options && options.onDismiss && options.onDismiss();
        }
      }
    );
  }
}

module.exports = Alert;

When I run it though the documenation.build() ... documentation.format.md() I get this markdown

<!-- Generated by documentation.js. Update this documentation by updating the source code. -->

## 

Copyright (c) 2015-present, Facebook, Inc.
All rights reserved.

This source code is licensed under the BSD-style license found in the
LICENSE file in the root directory of this source tree. An additional grant
of patent rights can be found in the PATENTS file in the same directory.

## Alert

Launches an alert dialog with the specified title and message.

Optionally provide a list of buttons. Tapping any button will fire the
respective onPress callback and dismiss the alert. By default, the only
button will be an 'OK' button.

This is an API that works both on iOS and Android and can show static
alerts. To show an alert that prompts the user to enter some information,
see `AlertIOS`; entering text in an alert is common on iOS only.

## iOS

On iOS you can specify any number of buttons. Each button can optionally
specify a style, which is one of 'default', 'cancel' or 'destructive'.

## Android

On Android at most three buttons can be specified. Android has a concept
of a neutral, negative and a positive button:

-   If you specify one button, it will be the 'positive' one (such as 'OK')
-   Two buttons mean 'negative', 'positive' (such as 'Cancel', 'OK')
-   Three buttons mean 'neutral', 'negative', 'positive' (such as 'Later', 'Cancel', 'OK')

By default alerts on Android can be dismissed by tapping outside of the alert
box. This event can be handled by providing an optional `options` parameter,
with an `onDismiss` callback property `{ onDismiss: () => {} }`.

Alternatively, the dismissing behavior can be disabled altogether by providing
an optional `options` parameter with the `cancelable` property set to `false`
i.e. `{ cancelable: false }`

Example usage:

    // Works on both iOS and Android
    Alert.alert(
      'Alert Title',
      'My Alert Msg',
      [
        {text: 'Ask me later', onPress: () => console.log('Ask me later pressed')},
        {text: 'Cancel', onPress: () => console.log('Cancel Pressed'), style: 'cancel'},
        {text: 'OK', onPress: () => console.log('OK Pressed')},
      ],
      { cancelable: false }
    )

## AlertAndroid

Wrapper around the Android native module.

Problem is, as you'll notice on line 3, there is an empty ## which is breaking things in ast. Am I missing something or is this a bug?

[tmcw]

You probably want to chop of the second * on that initial code comment, to prevent the license declaration being parsed as documentation. So, the first two lines would be:

/*
 * Copyright (c) 2015-present, Facebook, Inc.

[fourcolors]

@tmcw hm... this might be an issue to do because I'm pulling in ReactNative's source code for this particular parse. It's good to know the culprit though. Is there a way to remove this when I do a .build or format?

[tmcw]

I don't completely understand - why would that be an issue? You wouldn't remove the copyright comment, you'd only remove the second * that precedes it, since it isn't meant to be a documentation comment.

[fourcolors]

@tmcw right, what I mean is, am I able to do this with .build or do I need to open the file up myself and do the parsing before I run it though the builder. ie: does .build let me filter each line of the doc or something like that?

[fourcolors]

@tmcw Oh, I guess the doc that .build creates is an array I can filter though. Ok, sorry didn't understand that. I have what I need now. Thanks!

[arv]

Is it attaching a comment to the 'use strict' expression?

[tmcw]

Yes, and afaik that's the correct behavior. The first doc block doesn't define itself as a @module or anything else that would hide it from display as a documentation chunk.

[tdmalone]

To others coming across this who were looking how to create a file-level docblock - see http://usejsdoc.org/tags-file.html, noting that you need to provide the description in a @file tag (although, that doesn't seem to be correctly parsed by Documentation, so I'll log a separate issue about that).