Skip to content

Commit 114df16

Browse files
authored
docs: add missing diagnostics and settings. (#50)
* fix: missing diagnostics * fix: missing settings * docs: move API of docScriptPath to export-docs
1 parent c944d9f commit 114df16

File tree

3 files changed

+224
-12
lines changed

3 files changed

+224
-12
lines changed

src/content/wiki/diagnostics.mdx

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -124,7 +124,7 @@ The codestyle group contains diagnostics for maintaining a good code style.
124124
</Fragment>
125125
**Default File Status:** `"None"`
126126

127-
Triggered when the opinionated style checking detects an incorrectly styled line.
127+
Triggered when the opinionated style checking detects an incorrectly styled line. The style can be customized using the [`Lua.format.defaultConfig` setting](/wiki/settings#formatdefaultconfig).
128128

129129
</Diagnostic>
130130

@@ -134,7 +134,7 @@ Triggered when the opinionated style checking detects an incorrectly styled line
134134
</Fragment>
135135
**Default File Status:** `"None"`
136136

137-
Triggered when the opinionated style checking detects an incorrectly named element.
137+
Triggered when the opinionated style checking detects an incorrectly named element. The style can be customized using the [`Lua.nameStyle.config` setting](/wiki/settings#namestyleconfig).
138138

139139
</Diagnostic>
140140

@@ -144,7 +144,7 @@ Triggered when the opinionated style checking detects an incorrectly named eleme
144144
</Fragment>
145145
**Default File Status:** `"None"`
146146

147-
Triggered when a typo is detected in a string. The dictionary can be customized using the [`Lua.spell.dict` setting](https://github.com/LuaLS/lua-language-server/wiki/Settings#spelldict).
147+
Triggered when a typo is detected in a string. The dictionary can be customized using the [`Lua.spell.dict` setting](/wiki/settings#spelldict).
148148

149149
</Diagnostic>
150150

@@ -334,7 +334,7 @@ Triggered when there are two [`@param`](/wiki/annotations#param) annotations wit
334334
</Fragment>
335335
**Default File Status:** `"None"`
336336

337-
Triggered when a functions signature is partially documented with [annotations](/wiki/annotations), but the annotations do not cover every element of the signature.
337+
Triggered when a functions signature is partially documented with [annotations](/wiki/annotations), but the annotations do not cover every element of the signature.
338338
E.g. one of the parameters is not annotated, or the return value is not annotated.
339339

340340
</Diagnostic>
@@ -468,6 +468,14 @@ Triggered when the returns of a function are being ignored when it is not permit
468468

469469
</Diagnostic>
470470

471+
<Diagnostic level="Warning">
472+
<Fragment slot="name">
473+
### invisible
474+
</Fragment>
475+
Triggered when accesses to fields which are invisible. Specifically, access to [`@package`](/wiki/annotations#package) from another file, [`@private`](/wiki/annotations#private) not within self class, or [`@protected`](/wiki/annotations#protected) not within self class or child classes.
476+
477+
</Diagnostic>
478+
471479
## strong
472480

473481
The strong group contains diagnostics considered "strong". These can help you write better code but may require more work to follow.

src/content/wiki/export-docs.mdx

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -266,3 +266,31 @@ import vscodeImg from "~/assets/images/vscode.svg"
266266

267267
</div>
268268
</Tabs>
269+
270+
## Custom
271+
272+
By specifying [`Lua.docScriptPath` setting](/wiki/settings#docscriptpath), you could override the default documentation generation behavior. When set, the server uses this script (instead of [the built-in one](https://github.com/LuaLS/lua-language-server/blob/master/script/cli/doc/export.lua)) to generate LuaDocs, allowing customization of filtering, sorting, and formatting rules. Leave empty to use the default script. Requires the custom script to implement specific APIs for compatibility.
273+
274+
<Accordion>
275+
276+
<span slot="summary">API</span>
277+
278+
```Lua
279+
export.getLocalPath(uri) -- Called when the documentation needs to get the path of a source relative to the DOC path. Returns the relative path, or the absolute path, prefixed with the string '[FOREIGN]'
280+
281+
export.positionOf(rowcol) -- Wrapper for guide.positionOf(rowcol[1], rowcol[2])
282+
283+
export.sortDoc(a,b) -- A comparison function used by table.sort that is used to sort every piece of documentation in alphabetical order.
284+
285+
export.documentObject(source, has_seen) -- A function that gets called on every source object. It is responsible for filtering each source to their corresponding export.makeDocObject[<TYPE>] function
286+
287+
export.makeDocObject[<TYPE>] -- A table of functions that are responsible for building their corresponding <TYPE>'s documentation. TYPES include 'type', 'variable', 'doc.class', etc. 'INIT' corresponds to every documentation object before it is processed by its corresponding type.
288+
289+
export.gatherGlobals() -- Called when the documentation needs an exhaustive list of the globals it should export documentation. By default this includes the result of vm.getAllGlobals(). Returns the collected variables/types.
290+
291+
export.makeDocs(globals, callback) -- Documents globals from export.gatherGlobals() by calling export.documentObject on each one; updates its progress by calling callback when a global is finished being documented. Returns a table of the collected documentation
292+
293+
export.serializeAndExport(docs, outputDir) -- Serializes documentation tables from export.makeDocs to json and markdown, Writes them to <outputDir>/doc.json and <outputDir>/doc.md, respectively. Returns these paths.
294+
```
295+
296+
</Accordion>

0 commit comments

Comments
 (0)