Comments (2)
I really like this idea. One question I have is how should we show documentation comments if they differ for each overload (which presumably they would, at least for different arguments). Maybe have a single page for the overloads but list each one in normal detail below? I guess we could also compare the comments for each method and argument and if they're identical across the overloads we could "collapse" the docs to a single page like Unity.
from statiq.docs.
It seems the merged style is more of an exception than the rule in how they organise their documentation. Physics2D.Raycast for example just lists the details of 3 different overloads with their full descriptions one after the other, essentially keeping them separate but still all on one page.
Even just doing that so the Methods list on the class page doesn't need to include all the parameters in the Name column would be nice. I currently have quite a few methods with multiple overloads that have one line summaries, but end up taking up several lines because it tries to squeeze their parameters into the tiny Name column. For example:
That could all be a single line.
Trying to collapse them automatically whenever all parameters that share a name also have the same comment sounds like it would work reasonably well.
Are there any sort of tags or anything that could be included in the comments to tell Wyam how to manage the overloads without affecting the way Visual Studio displays the tooltip or anything else?
On a somewhat related note, I don't even bother documenting the parameters or return type on most of my methods since the summary already explains enough. So those functions end up looking like the image below where the Parameters and Return Type tables don't even show anything the Syntax hasn't already said. In such cases I think it would be best to simply skipped the tables entirely.
from statiq.docs.
Related Issues (20)
- Make sure to escape all non-path chars in symbol names for docs
- Deconflict output files for symbols differing only by case in docs
- Docs Recipe - no setting for includeProtected (AnalyzeCSharp.WherePublic)
- Nested types cause URL conflicts for Docs recipe HOT 1
- Docs search breaks on digits
- Material theme for docs HOT 2
- Add xrefs for all API symbols
- Support for Markdown format
- Verify doc comments specification HOT 1
- Feature Request: support XML <include> tags
- GetTypeLink fails for tuples HOT 6
- Add support for automatically linking symbols
- Add support for langword
- Add the props file from Statiq.Web to Statiq.Docs HOT 2
- AddAssemblyFiles to populate "API"?
- Source files are ignored by generator HOT 11
- Xrefs for API symbols should not contain whitespace
- Methods from base class not listed if base class is generic
- Example on Statiq.Docs output HOT 1
- File Casing issue when deploying to GH-Pages HOT 1
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from statiq.docs.