New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add XML docs to enhance discoverability in IDEs #4

Closed
bartsokol opened this Issue Jan 30, 2018 · 9 comments

Comments

2 participants
@bartsokol
Member

bartsokol commented Jan 30, 2018

Add XML docs to extensions, so that one can see what does given function do without the need to dig into docs. From the other side, XML docs can also be used do generate docs for the library's API.

@pizycki

This comment has been minimized.

Contributor

pizycki commented Jan 30, 2018

I'll have a look at it.

@pizycki

This comment has been minimized.

Contributor

pizycki commented Feb 3, 2018

Just started working on it.
Here is the first commit with documentation for Result structure pizycki@a2df319

I assumed that Result can become Success or Failure and that way I'd like to continue commenting the code. If you have any thoughts on this, please share.

The english might not be perfect, so if something doesn't sounds good and should be rewritten, point it out as well.

@bartsokol

This comment has been minimized.

Member

bartsokol commented Feb 3, 2018

Good start 👍 I will add some comments to the commit, feel free to reply and point out good and bad ideas ;)

As for the ways to call the paths, I'm thinking of using the track naming, like "Result is on success track" or "Result is on error track" to indicate the path. Thoughts?

And don't worry about the language at this point, we can do final review once all is done and improve it if there will be such need :)

@pizycki

This comment has been minimized.

Contributor

pizycki commented Feb 3, 2018

Cool, i'll continue working on this weekend :)

@bartsokol bartsokol added this to the 0.2 milestone Feb 3, 2018

@bartsokol bartsokol added this to To Do in Release version 1.0 via automation Feb 3, 2018

@bartsokol bartsokol moved this from To Do to In Progress in Release version 1.0 Feb 3, 2018

@bartsokol

This comment has been minimized.

Member

bartsokol commented Feb 3, 2018

I've added some sample docs in this PR, feel free to comment there as well and use it as an example.

@pizycki

This comment has been minimized.

Contributor

pizycki commented Feb 4, 2018

Just updated Result doc in this commit pizycki@af1c9ea

@pizycki

This comment has been minimized.

Contributor

pizycki commented Feb 8, 2018

Updates in-code doc for Unit and Option.
I didn't want to document ErrorDetails as I'm not sure how it's supposed to work. I think I'll need some examples for this.

@bartsokol

This comment has been minimized.

Member

bartsokol commented Feb 8, 2018

I've recently created develop branch where I will be merging changes in preparation for release. Please rebase your branch on it, there are some new docs merged there as well.

If you won't be sure what to put in the docs for some type or method you can leave it to me or put TODO in comments and we can work on it together when the PR will be created.

@bartsokol bartsokol referenced this issue Feb 12, 2018

Merged

Docs update #13

@bartsokol

This comment has been minimized.

Member

bartsokol commented Mar 1, 2018

Documentation added in version 0.2.0 :)

@bartsokol bartsokol closed this Mar 1, 2018

Release version 1.0 automation moved this from In Progress to Done Mar 1, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment