WordPress.org

Make WordPress Core

Opened 2 years ago

Closed 2 years ago

Last modified 21 months ago

#43270 closed defect (bug) (fixed)

JSDoc: wp-admin/js/user-suggest.js

Reported by: timhavinga Owned by: atimmer
Milestone: 5.1 Priority: normal
Severity: normal Version:
Component: Networks and Sites Keywords:
Focuses: javascript, docs, multisite Cc:

Description

Add documentation to the user-select.js file.

Attachments (1)

43270.patch (1.9 KB) - added by timhavinga 2 years ago.

Download all attachments as: .zip

Change History (11)

@timhavinga
2 years ago

#1 @timhavinga
2 years ago

Two questions remain:

  • I added an @see in the documentation to refer to the PHP function that handles the AJAX call performed in this script. Is this the preferred way to document this?
  • The input field has optional data-attributes. How to document these?

This ticket was mentioned in Slack in #core-js by atimmer. View the logs.


2 years ago

#3 @atimmer
2 years ago

  • Summary changed from JSDoc: wp-admin/js/user-select.js to JSDoc: wp-admin/js/user-suggest.js

#4 @atimmer
2 years ago

  • Owner set to atimmer
  • Resolution set to fixed
  • Status changed from new to closed

In 42708:

Docs: Improve JSDoc for wp-admin/js/user-suggest.js.

Props timhavinga.
Fixes #43270.

#5 follow-up: @atimmer
2 years ago

Thank you for your contribution!

About your questions:

  • I've discussed this during the #core-js chat. The takeaway is that because this documentation is mainly for people reading the code, the way you have documented it is the way to go.
  • The optional data attributes are fairly specific to this use-case, so I would say that the way you documented it is great. It is human readable and I don't think we need a repeatable way to do this.

I made a one change before committing:

  • Reformatted the second doc block to have a clear short description and a longer description.

#6 in reply to: ↑ 5 @timhavinga
2 years ago

Thank you for the feedback and your kind words!

Replying to atimmer:

I made a one change before committing:

  • Reformatted the second doc block to have a clear short description and a longer description.

One small detail: in reformatting, the line endings of the second doc block are no longer at the specified 80 character limit.

#7 @atimmer
2 years ago

In 42714:

Docs: Improve JSDoc for wp-admin/js/user-suggest.js.

Amend r42708 by fixing the 80 character wrap around.

Props timhavinga.
See #43270.

#8 @atimmer
2 years ago

Thank you, I've fixed this in my last commit.

#9 @netweb
2 years ago

  • Milestone changed from Awaiting Review to 5.0

#10 @flixos90
21 months ago

  • Milestone changed from 5.0 to 5.1
Note: See TracTickets for help on using tickets.