Reference Guide or Documentation for FeatureScript Docs Comments?

orion_deyoe

Does official documentation exist for the docs comment syntax in FeatureScript? These are the comments that start with "/**" and generate the popups that appear when hovering over a function or type.

I have been able to figure out a few things from the std source as well as trial and error but searching for real documentation on all of the keywords and brackets and such has been fruitless.

Specifically right now I'm stuck on trying to force a newline in the docs to show something like a list.

S1mon

https://cad.onshape.com/FsDoc/index.html

It's pretty much all documented there.

orion_deyoe

No, it is not. I have been through every piece of documentation on this page and there is not a single reference to the "/**" style of comment or any of the syntax for formatting them. I am not talking about a standard "/* */" block comment here. I have looked through a decent amount of standard library source code to pull out what I could, but it is not easily searchable and many of the functions in that code have extremely minimal docs comments so they aren't even good examples of what I'm looking for.

S1mon

From my agent…

The /** ... */ blocks in the Onshape standard library are FsDoc-style documentation comments, very close in spirit to JSDoc.

Key patterns:

• /** marks a doc comment that FsDoc can pick up for generated API docs.
• Lines usually start with *, then close with */.
• A short prose summary comes first.
• Tags describe API shape:
  • @param name {Type} : description
  • @returns {Type} : description
  • @type {{ ... }} for documented map/type shapes
  • @field name {Type} : description inside map/type docs
  • @optional , @requiredIf , @autocomplete , @eg , @ex
  • @seeAlso [symbol(...)]
  • @internal for things not intended as public API

Examples in the standard library:

• box.fs shows module-level docs, @type , @field , and short function comments.
• mateConnector.fs shows the rich feature-parameter style: @param definition {{ ... @field ... }}.
• splineUtils.fs shows @type , @seeAlso , @param , and @returns .
• properties.fs shows inline examples like @eg , links to docs/help pages, and property/type docs.

Practical takeaway: for custom FeatureScript, /** ... */ is the right format when documenting exported helpers, types, feature definitions, and structured definition maps. It is documentation only; it does not affect FeatureScript execution.

jnewth

Onshape docs are pretty lean in some areas, but overall they are fantastic. Your best resource for writing FS is the std library itself. @S1mon 's strategy is a good one: give the codebase to an AI. To that end, one enormously useful tool is @javawizard 's std library mirror: https://github.com/javawizard/onshape-std-library-mirror

It hasn't been bumped recently which makes me nervous that he's run afoul of the api pricing changes but @javawizard provides a tool to write your own importer as well: https://github.com/javawizard/onshape-std-library-importer