Morebits: add documentation #481
Conversation
…e highlights, rearranged functions to a more logical order, to roughly match with the order in the original doc comment
|
Hey can someone merge this please! This is just a documentation upgrade. Nothing to be tested. I feel that this will help new developers get acquainted with the twinkle codebase more easily. |
morebits.js
Outdated
| /** | ||
| * Gives an array of substrings of `str` starting with `start` and | ||
| * ending with `end`, which is not in `skiplist` | ||
| * @param {string} str @param {string} start @param {string} end @param {(array|string)} [skiplist] |
There was a problem hiding this comment.
Is this valid JSDoc? Either way, I'd argue having each param on a newline is easier on the eyes.
There was a problem hiding this comment.
Since the description makes it clear the functionality of each parameter, I thought I'd rather not waste space putting each on a new line.
Fixed now.
| }; | ||
|
|
||
| /** | ||
| * `pageText` - string containing the updated page text that will be saved when save() is called |
There was a problem hiding this comment.
why not use JSDoc syntax here? (and elsewhere below)
There was a problem hiding this comment.
Because of the odd behaviour it causes (in my editor, VScode, at least): putting @param makes the tooltip unnecessarily carry the parameter's description twice. Once at the top: just below the function prototype and once again in the parameters' section. This is especially poor-looking for those large param descriptions like in this.setMinorEdit().
Make it jsdocs if you feel like it.
| @@ -2847,7 +2940,7 @@ Morebits.wiki.page = function(pageName, currentAction) { | |||
| }; | |||
| }; // end Morebits.wiki.page | |||
|
|
|||
| /** Morebits.wiki.page TODO: (XXX) | |||
| /* Morebits.wiki.page TODO: (XXX) | |||
There was a problem hiding this comment.
Should probably be
/**
* Morebits.wiki.page TODO: (XXX)
...
There was a problem hiding this comment.
No, because in that case, it gets treated as part of the doc comment for Morebits.wiki.preview (which is the next function after this).
|
Thanks for this. I'd love to see all of Twinkle have propoer JSDocs. This is a great start. |
* morebits: improve documentation of wiki.api, string, array classes * morebits: wiki.page: generate jsdoc comments on basis of existing doccomment * morebits: wiki.page: prune the doc comment at the top to show just the highlights, rearranged functions to a more logical order, to roughly match with the order in the original doc comment * morebits: use jsdocs on wiki.preview; minor changes to wiki.api * morebits: add jsdocs for wikitext.page + minor changes elsewhere
* morebits: improve documentation of wiki.api, string, array classes * morebits: wiki.page: generate jsdoc comments on basis of existing doccomment * morebits: wiki.page: prune the doc comment at the top to show just the highlights, rearranged functions to a more logical order, to roughly match with the order in the original doc comment * morebits: use jsdocs on wiki.preview; minor changes to wiki.api * morebits: add jsdocs for wikitext.page + minor changes elsewhere
wikimedia-gadgets#481 removed a ton of functions
morebits: add back function accidentally removed in #481
Added some documentation (jsdocs) for several of morebits classes. Since jsdocs are shown by code editors in tooltips, this would greatly help the next generation of script writers.
I converted existing documentation comments to jsdoc-comments for wiki.page, wiki.api, wiki.preview, string, array, regexp classes while adding my own $0.02 here and there. For wikitext.page, it is written from scratch.
In the 3rd commit, I rearranged the order of several functions in wiki.page, hence the diff for that class may look quite messy.