search

maythamfahmi / CryptoNet

CryptoNet is simple, fast and a lightweight asymmetric and symmetric encryption library.
https://github.com/maythamfahmi/CryptoNet
MIT License
101 stars 19 forks source link

[feature request]: Inline documentation with description #104

Closed maythamfahmi closed 2 weeks ago

maythamfahmi commented 1 month ago

Contact Details

No response

Is your feature request related to a problem? Please describe.

n/a

Describe the solution you'd like

It would be good a some pont when version 3 at its end, an inline documenation to be add to constructors and method.

Describe alternatives you've considered

No response

Additional context

No response

Priority Level

Low

Code of Conduct

jwdonahue commented 1 month ago

What kind of "inline" documentation?

XML comments:

/// <Summary>
/// Constructor...
/// </Summary>

Or something else?

maythamfahmi commented 1 month ago

exactly XML comments.

jwdonahue commented 1 month ago

Okay, I'll start weaving those into any work I do.

If we add: <GenerateDocumentationFile>True</GenerateDocumentationFile> to the .csproj files, then it will start issuing warnings for missing XMLDoc comments on all publicly visible members, not just the constructors.

I've been doing that in a lot of my own projects over at the SharperHack-org project. I've actually been considering keeping the comments, but dropping the XMLDoc format. That or I really need to figure out how to wire up the output xml output files, into some sort of organized set of web pages.

The thing that's always annoyed me about them, is the source comments can become difficult to read, when you start adding references or lots paragraph tags. I am starting to lean towards a more readable non-XMLDoc format for the comments, and either forgo the eventual web docs integration, or find/create a better tool for a simpler, more readable comment format.

maythamfahmi commented 1 month ago

Good input. My primary thought was about the documentation information that pops up when using IntelliSense.

jwdonahue commented 1 month ago

I'd have to verify, but I think IntelliSense picks up the summary and the listed exceptions, if the XmlDoc tags are there, but defaults to some number of whatever comments are associated with the method. At least that's the recollection I have from decades past.

But ya, I agree, developer supports are very important.

maythamfahmi commented 2 weeks ago

old documentation is ported to docfx https://maythamfahmi.github.io/CryptoNet, but under API new version3 is found. When we are about the endpoint version 3 relase, we will update the examples in seperate feature branch related to #123