Update `dox` to latest version and fix some documentation issues #12024

hasezoey · 2022-06-30T16:10:27Z

Summary

This PR updates dependency dox from 0.3.1(from 2015) to 0.9.1(from 2022), which should address #8925 at least a little

re #8925

This PR:

upgrades dox through the versions, a commit made each time a "minor" version was updated or when a change was required.
does not guarantee that all anchors or stuff are the same, i had modified some things to be more consistent so some could have changed.
should make debugging easier when dox fails with a error (5de8b9a)
adds yarn.lock got gitignore (because package-lock.jsonwas already in it)
fixes empty @returns tags to be properly set (meaning to have types)
fixes wrong array usage (things like [Type] were used when jsdoc only allows Type[] or Array<Type>)
removes function definitions from VirtualType.prototype.set and VirtualType.prototype.get because they were not proper jsdoc (also dox did not want to correctly register things like @callback or @typedef or @type with @name) (7155089)
adds many @memberOf tags to many jsdoc comments (because they were missing and resulting in wrong documentation)
fixes SchemaType.prototype.castFunction being listed as cast
removes @static and @function from SchemaType.prototype.castFunction
moves the jsdoc for DocumentArrayPath.set and SubdocumentPath.set to the correct location
replaces all (that i found) occurrences of - in @param descriptions, because they were making the documentation formatting weird (e57594c)
replaces all found occurrences of @param {*} with @param {Any} to be more consistent and also because * was making the documentation formatting weird (953853f)
removes all text after @static because in later versions of dox nothing was given to the processing anymore and was also not proper jsdoc (but things are still defined thanks to other things) (1719bf6)
adds a new property to ctx in docs/source/api.js named isFunction that after processing adds () to the end of the ctx.string, this was done because things like @function and @static could be in a different sequence than expected
changes to use ctx.constructor over data.name for static properties (to be consistent with non-static properties) (cfe7248)
removes a debug log of the ctx (39a02a1)

PS: this PR also fixes some documentation issues that are visible in current master

Note: please only someone with knowledge of how the documentation works merge this PR

This change is required because since dox 0.5.0 a error will be thrown if "return" present but empty This change also extends the message to say what gets returned

@callback

…Type.set" This is because dox (jsdoctypeparser@1.2.0) does not seem to recognize "@callback" or "@typedef" with "@name"

…e.Collection"

… "QueryCursor.prototype[Symbol.asyncIterator]"

…stFunction"

…unction"

This also changes the description for the parameters to match "SchemaType.set" and not cause bad formatting Also upates the return type to "void"

This also sometimes somehow messes-up the documentation styling

The things that were defined there are set via other things anyway, and many did not even have it set

This also changes the description for the parameters to match "SubdocumentPath.set" and not cause bad formatting Also upates the return type to "void"

…y adding "()"

…unction" and "static" This fixes static "Schematype" properties to be in a different case than instance properties

hasezoey · 2022-07-02T12:00:22Z

Note: there are currently conflicts with the base branch, but i will resolve them once it is ready for merge (after having had reviews)

lib/connection.js

lib/error/index.js

…s loop This will make setting "ctx.string" consistently and should make it independent of tag order (Also thanks to the previous commit warns against both "instance" and "static")

…Map" to reflect actual name

…and add "@static"

…memberOf" handling

… result in a empty field

…ber all values This makes use of https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html and is still fully compatible with plain js

This currently does not add anything to the final documentation, because i dont know which style it should be

hasezoey

I have now updated the branch to include the latest master again (because documentation changes were made), and i also have touched-up some of the documentation again, which includes:

adding some comments to signal what is doing what
move most string manipulation handling to after the "tags" loop
add a jsdoc "typedef" to remember all properties
add a proper type for @returns {void} or {undefined} as to not result in empty fields

Also some other discussion questions:

should tags and handling for @receiver be removed and be replaced with the proper tags everywhere?
should {Any} maybe be replaced again everywhere with {*}? because by jsdoc definition {*} is the proper "any" type, but currently otherwise causing some documentation style problems

hasezoey · 2022-07-03T11:44:03Z

docs/source/api.js

+          case 'deprecated':
+            ctx.deprecated = true;
+            break;


i have now included basic handling for @deprecated tag, but i am not sure where or in what style it should appear in the documentation

docs/source/api.js

hasezoey · 2022-07-04T11:02:20Z

Made another small update which does:

fix Aggregate.prototype.lookup not having a proper next line for a jsdoc tag
re-adding null to listed types when nullable
fixing Query.prototype.box jsdoc to be proper jsdoc and extending the comment for the parameters (please check if correct, i am not familiar with that function)
fixing @type tags not being properly escaped with { and }

Edit:
some other following changes:

add : to the end of all jsdoc headers that have #### to make them consistent
change parsed @return tag descriptions to overwrite property description instead of using a new property return, this was made because property return was never used and i am not familiar enough with pug
also changed the second @return parsing replace to allow for \n at the end (which seems to be common now)

…stead of adding to "return" This is changed because "return" property was never used, but the "description" was (in pug files) but i am not familiar with pug to change that Also updates the second "replace" call because "\n" is mostly added to the end which makes it ineffective

This is to change the style to be consistent and headers with ":" seem to be the most used, so it was changed to that

hasezoey · 2022-07-04T12:50:13Z

I would say this PR is finished for changes, unless some are requested / merging latest master, some changes could probably be put in their own PR / cherry-picked to land sooner.

i would like to request @vkarpov15 to review this PR for correctness

vkarpov15

Code is LGTM. I'll review this more after I merge, it's easier to test after merging to master because we don't have deployment previews.

hasezoey · 2022-07-08T10:15:09Z

we don't have deployment previews.

isnt the script docs:view a deployment preview or do you maybe mean compiled documentation diff?

PS: also there were still some open discussion questions

hasezoey added 26 commits June 30, 2022 14:22

chore: add yarn.lock to ignore

46073dd

chore: upgrade "dox" to "0.4.4"

f0fa4b5

chore: upgrade "dox" to "0.4.5"

a889e3a

chore(docs/source/api.js): add log of file when "parseComments" errors

5de8b9a

style: fix empty "returns" jsdoc for "syncIndexes"

aa297ba

This change is required because since dox 0.5.0 a error will be thrown if "return" present but empty This change also extends the message to say what gets returned

style: fix empty "returns" jsdoc for "buildBulkWriteOperations"

b4c26a4

This change is required because since dox 0.5.0 a error will be thrown if "return" present but empty This change also extends the message to say what gets returned

chore: upgrade "dox" to "0.5.3"

c42bdba

style: properly define Document Arrays in jsdoc

dce32d5

style: remove function definition from "VirtualType.get" and "Virtual…

7155089

…Type.set" This is because dox (jsdoctypeparser@1.2.0) does not seem to recognize "@callback" or "@typedef" with "@name"

style: add jsdoc tags "memberOf" and "instance" to "Mongoose.prototyp…

c22e7cf

…e.Collection"

style: add jsdoc tag "memberOf" to "Model.prototype.increment"

97b47c3

style: add jsdoc tag "memberOf" to "QueryCursor.prototype.map"

a6c9834

style: change jsdoc tag "memberOf" to point to the correct member for…

0354bb5

… "QueryCursor.prototype[Symbol.asyncIterator]"

style: add jsdoc tag "memberOf" to "AggregationCursor.prototype.map"

48beee1

style: properly set jsdoc tag "function" for "SchemaType.prototype.ca…

7646125

…stFunction"

style: remove and add some jsdoc tags for "SchemaType.prototype.castF…

82a8c03

…unction"

style: move jsdoc comment to proper function ("DocumentArrayPath.set")

cb8e66a

This also changes the description for the parameters to match "SchemaType.set" and not cause bad formatting Also upates the return type to "void"

style: replace all "@param {*}" with "@param {Any}" to match other cases

953853f

style: remove "- " before description to be more consistent

e57594c

This also sometimes somehow messes-up the documentation styling

style: remove extra parameters from "@static"

1719bf6

The things that were defined there are set via other things anyway, and many did not even have it set

style: move jsdoc comment to proper function ("SubdocumentPath.set")

590f0ff

This also changes the description for the parameters to match "SubdocumentPath.set" and not cause bad formatting Also upates the return type to "void"

chore: upgrade "dox" to "0.8.1"

dbc078b

chore: upgrade "dox" to "0.9.1"

728d967

chore(docs/source/api): change to use "isFunction" instead of directl…

96e1ffd

…y adding "()"

chore(docs/source/api): use "ctx.constructor" over "data.name" for "f…

cfe7248

…unction" and "static" This fixes static "Schematype" properties to be in a different case than instance properties

chore(docs/source/api): remove console.log of the "ctx"

39a02a1

Merge branch 'master' into updateDox

bb0bf63

Uzlopak reviewed Jul 2, 2022

View reviewed changes

lib/connection.js Outdated Show resolved Hide resolved

Uzlopak reviewed Jul 2, 2022

View reviewed changes

lib/error/index.js Show resolved Hide resolved

hasezoey added 9 commits July 3, 2022 12:34

chore(docs/source/api): rename "ctx.static" to "ctx.isStatic"

a006214

chore(docs/source/api): move setting of "ctx.string" to after the tag…

17c7e63

…s loop This will make setting "ctx.string" consistently and should make it independent of tag order (Also thanks to the previous commit warns against both "instance" and "static")

style: update jsdoc "memberOf" for "MongooseMap.prototype.$isMongoose…

73f3400

…Map" to reflect actual name

style: set proper jsdoc "memberOf" path for "MongooseBuffer.mixin.*" …

6c0e316

…and add "@static"

chore(docs/source/api): remove redundant setting of "isFunction" in "…

da57bf2

…memberOf" handling

chore(docs/source/api): add more comments explaining what some things do

9f73623

chore(docs/source/api): add "void" to types in return, so it does not…

fcb2bfc

… result in a empty field

chore(docs/source/api): add some jsdoc-typescript types to help remem…

cf6ad88

…ber all values This makes use of https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html and is still fully compatible with plain js

chore(docs/source/api): add handling for "@deprecated" and property

ec947f6

This currently does not add anything to the final documentation, because i dont know which style it should be

hasezoey commented Jul 3, 2022

View reviewed changes

hasezoey added 4 commits July 4, 2022 12:07

style: properly escape "@type" type parameters

5d80579

style: fix missing next line in jsdoc for "Aggregate.prototype.lookup"

906cb4f

chore(docs/source/api): re-add "null" to types when nullable

e6776b3

style: update "Query.prototype.box" jsdoc to use proper "@param" tags

a1eade6

hasezoey added 2 commits July 4, 2022 13:15

style: add ":" to all jsdoc headers where missing

6a10d4f

This is to change the style to be consistent and headers with ":" seem to be the most used, so it was changed to that

vkarpov15 approved these changes Jul 8, 2022

View reviewed changes

Merge branch 'master' into updateDox

1cc2293

vkarpov15 added this to the 6.4.4 milestone Jul 8, 2022

vkarpov15 merged commit d80a2ee into Automattic:master Jul 8, 2022

vkarpov15 added a commit that referenced this pull request Jul 8, 2022

docs: clean up some API issues re: #12024

14fd916

hasezoey deleted the updateDox branch July 8, 2022 10:20

This was referenced Jul 8, 2022

Documentation-Generation remove .prototype. fix-up code #12071

Merged

Refactor all @receiver tags to proper jsdoc tags #12072

Merged

[Docs] Make use of the deprecated tag available in jsdoc for documentation #12080

Closed

hasezoey mentioned this pull request Jul 23, 2022

docs(api_split): add basic DEPRECATED output #12146

Merged

vkarpov15 mentioned this pull request Sep 27, 2022

Use something other than dox to parse documentation #8925

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update `dox` to latest version and fix some documentation issues #12024

Update `dox` to latest version and fix some documentation issues #12024

hasezoey commented Jun 30, 2022 •

edited

hasezoey commented Jul 2, 2022

hasezoey left a comment

hasezoey Jul 3, 2022

hasezoey commented Jul 4, 2022 •

edited

hasezoey commented Jul 4, 2022 •

edited

vkarpov15 left a comment

hasezoey commented Jul 8, 2022 •

edited

Update dox to latest version and fix some documentation issues #12024

Update dox to latest version and fix some documentation issues #12024

Conversation

hasezoey commented Jun 30, 2022 • edited

hasezoey commented Jul 2, 2022

hasezoey left a comment

Choose a reason for hiding this comment

hasezoey Jul 3, 2022

Choose a reason for hiding this comment

hasezoey commented Jul 4, 2022 • edited

hasezoey commented Jul 4, 2022 • edited

vkarpov15 left a comment

Choose a reason for hiding this comment

hasezoey commented Jul 8, 2022 • edited

Update `dox` to latest version and fix some documentation issues #12024

Update `dox` to latest version and fix some documentation issues #12024

hasezoey commented Jun 30, 2022 •

edited

hasezoey commented Jul 4, 2022 •

edited

hasezoey commented Jul 4, 2022 •

edited

hasezoey commented Jul 8, 2022 •

edited