Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[FEATURE] Align JSDoc template & plugin with OpenUI5 1.87.0 #572

Merged
merged 2 commits into from
Jan 25, 2021

Conversation

codeworrior
Copy link
Member

Includes the following changes

  • [INTERNAL] Update copyright year to 2021
    SAP/openui5@bc6825e48

  • [FIX] Corrected regular expression (SAPHosted)
    SAP/openui5@319798593

  • [FEATURE] Improve documentation for restricted APIs
    SAP/openui5@cb855596b

    • generated "auto-doc" honors visibility of target class. If target
      class is restricted, generated documentation also has visibility
      restricted
    • for restricted APIs, export the list of allowed consumers to
      api.json (property name 'allowedFor')
    • fix split of allowed consumers in tag handler for '@ui5-restricted'
      (comma is the only valid separator)
  • [FEATURE] Added FAQ section in ApiRef
    SAP/openui5@8d2d85e69

    An extra FAQ section will be displayed in ApiRef whenever
    FAQ content is specified.

  • [INTERNAL] Change to inclusive term "excluded"/"included"
    SAP/openui5@7b2ac1edb

  • [INTERNAL] Add missing props to event metadata
    SAP/openui5@ab7ab07ea

    The properties 'allowPreventDefault' and 'enableEventBubbling' had
    been missing in the API summary (api.json) for events.

  • [INTERNAL] Make interface validation more robust
    SAP/openui5@32f59b31c

    The validation of an implementation against an implemented interface
    should not crash when the implementation has no methods at all.

  • [INTERNAL] Minor improvements of template
    SAP/openui5@e766eeee5

  • [INTERNAL] Handling of defaultValues, error logging
    SAP/openui5@3bd509b1f

    A default value of "" (empty string) was not handled properly when
    generating auto-doc comments and a default value of "undefined" was
    not represented in the final api.json.

    To avoid confusion in the log, errors that do not break the build are
    no longer reported as errors, but as 'future errors'.

    APIs that can only be addressed via their global name, not via an AMD
    dependency, can now be marked with @ui5-global-only. They are no
    longer reported as errors during the build (as they can't be fixed).

  • [INTERNAL] Export only valid 'since' values
    SAP/openui5@a58310b2d

  • [INTERNAL] Normalize notation for generic types
    SAP/openui5@6e4e0ea87

    For generic types, JSDoc allows two different notations, one with a
    dot between the type's name and the type parameters (e.g.
    Array.) and one without the dot. The documentation for the
    Google Closure Compiler (to which JSDoc refers) already rates the
    notation with the dot as 'deprecated' (see
    https://github.com/google/closure-compiler/wiki/Types-in-the-Closure-Type-System
    , Type Application), JSDoc doesn't.

    However, as the notation without the dot is also common to TypeScript
    developers, all types in the api.json will now be normalized to that
    notation.

  • [INTERNAL] Add default value to JSDoc
    SAP/openui5@bb6001950

    Adding default values of function parameters to JSDoc conform notation

Thank you for your contribution! 🙌

To get it merged faster, kindly review the checklist below:

Pull Request Checklist

Includes the following changes

- [INTERNAL] Update copyright year to 2021
  SAP/openui5@bc6825e48

- [FIX] Corrected regular expression (SAPHosted)
  SAP/openui5@319798593

- [FEATURE] Improve documentation for restricted APIs
  SAP/openui5@cb855596b

  - generated "auto-doc" honors visibility of target class. If target
    class is restricted, generated documentation also has visibility
    restricted
  - for restricted APIs, export the list of allowed consumers to
    api.json (property name 'allowedFor')
  - fix split of allowed consumers in tag handler for '@ui5-restricted'
    (comma is the only valid separator)

- [FEATURE] Added FAQ section in ApiRef
  SAP/openui5@8d2d85e69

  An extra FAQ section will be displayed in ApiRef whenever
  FAQ content is specified.

- [INTERNAL] Change to inclusive term "excluded"/"included"
  SAP/openui5@7b2ac1edb

- [INTERNAL] Add missing props to event metadata
  SAP/openui5@ab7ab07ea

  The properties 'allowPreventDefault' and 'enableEventBubbling' had
  been missing in the API summary (api.json) for events.

- [INTERNAL] Make interface validation more robust
  SAP/openui5@32f59b31c

  The validation of an implementation against an implemented interface
  should not crash when the implementation has no methods at all.

- [INTERNAL] Minor improvements of template
  SAP/openui5@e766eeee5

- [INTERNAL] Handling of defaultValues, error logging
  SAP/openui5@3bd509b1f

  A default value of "" (empty string) was not handled properly when
  generating auto-doc comments and a default value of "undefined" was
  not represented in the final api.json.

  To avoid confusion in the log, errors that do not break the build are
  no longer reported as errors, but as 'future errors'.

  APIs that can only be addressed via their global name, not via an AMD
  dependency, can now be marked with @ui5-global-only. They are no
  longer reported as errors during the build (as they can't be fixed).

- [INTERNAL] Export only valid 'since' values
  SAP/openui5@a58310b2d

- [INTERNAL] Normalize notation for generic types
  SAP/openui5@6e4e0ea87

  For generic types, JSDoc allows two different notations, one with a
  dot between the type's name and the type parameters (e.g.
  Array.<string>) and one without the dot. The documentation for the
  Google Closure Compiler (to which JSDoc refers) already rates the
  notation with the dot as 'deprecated' (see
https://github.com/google/closure-compiler/wiki/Types-in-the-Closure-Type-System
  , Type Application), JSDoc doesn't.

  However, as the notation without the dot is also common to TypeScript
  developers, all types in the api.json will now be normalized to that
  notation.

- [INTERNAL] Add default value to JSDoc
  SAP/openui5@bb6001950

  Adding default values of function parameters to JSDoc conform notation
@coveralls
Copy link

coveralls commented Jan 25, 2021

Coverage Status

Coverage remained the same at 93.688% when pulling 7d1b103 on align-jsdoc-template-with-openui5-1.87.0 into cba257d on master.

@codeworrior codeworrior merged commit 0cb02ac into master Jan 25, 2021
@codeworrior codeworrior deleted the align-jsdoc-template-with-openui5-1.87.0 branch January 25, 2021 17:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants