Question: XML Comments

[VaclavElias]

Would it be possible to port all existing comments to/as XML documentation comments, so that they are available in IntelliSense and API docs?

/// <summary>
/// Some comments
/// </summary>

[VaclavElias]

If this is somehow resolved, I could create a PR for API docs like this one https://docs.bepuphysics.com/api/BepuPhysics.html which could be hosted in GitHub Pages, the same repository.

[ikpil]

I've given this some thought. Since the comments are being ported as-is, I'm being cautious because we need to be more careful during porting due to the possibility of divergence from the original source code.

[VaclavElias]

I see. Also the ported comments seem inconsistent. One way it could be done would be converting comments to XML only for API docs purpose. Not sure how feasible it would be long term.

Check this basic converter https://github.com/VaclavElias/Box2D.NET/blob/main/tools/Box2D.NET.CommentConverter/Program.cs

It runs through this action: https://github.com/VaclavElias/Box2D.NET/blob/main/.github/workflows/box2d-docs-github.yml

And this is the result, using docfx https://www.vaclavelias.com/Box2D.NET/api/Box2D.NET.html.

Another example: https://www.vaclavelias.com/Box2D.NET/api/Box2D.NET.B2World.html

Let me know if you would like a PR, even though it doesn't need to be merged, maybe so it is available for later or cherry pick if you are interested.

[ikpil]

I'm interested after seeing the result. Would you mind opening a PR?

[VaclavElias]

I will do that. Thanks for checking.

For now, I skip comments of type /**/, and the converter is only processing comments for public members.

I don't exclude ToDo comments. Maybe, good to have them visible for now.

There is definitelly more space for improvements because some Box2D comments are well structured but that could be done later.

[VaclavElias]

Related question: When you do your porting, do you automatically copy or sync the original comments?

I ask because improving the docs and fixing inconsistencies would ideally be done by contributing directly to the original Box2D repo, assuming those improvements would eventually sync to Box2D.NET.