Skip to content

Inkuire docs #2125

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.

Sign up for GitHub

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

Jump to bottom
Merged
merged 1 commit into from
Jul 28, 2021
Merged

Inkuire docs #2125

merged 1 commit into from
Jul 28, 2021

Conversation

KacperFKorban
Copy link
Member

Update documentation for Hoogle-like searches feature in new scaladoc.

BarkingBad
BarkingBad reviewed Jul 16, 2021
View reviewed changes
Copy link
Contributor

@BarkingBad BarkingBad left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changes look nice, but can we get some user manual either at docs.scala-lang page or at Inkuire README page on example queries etc.

@KacperFKorban
Copy link
Member Author

Attached gif:
inkuire-1 0 0-M2_js_flatMap

BarkingBad
BarkingBad reviewed Jul 27, 2021
View reviewed changes
Copy link
Contributor

@BarkingBad BarkingBad left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd rather see most of its content as a separate page under _overviews/scala3-scaladoc/inkuire.md and in scala3/scaladoc.md just quick info and link to the proper doc page.

@BarkingBad
Copy link
Contributor

As it comes to the content of the docs they seem sufficient, but maybe someone not familiar with the Inkuire should review them. Could you @julienrf take a look at whether docs are simple enough to comprehend?

romanowski
romanowski approved these changes Jul 27, 2021
View reviewed changes
Copy link

@romanowski romanowski left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Some comments but generally this docs strikes a nice balance in terms of length and amount of information provided.

scala3/scaladoc.md Outdated
- AndTypes, OrTypes and Functions have to be enclosed in parentheses e.g. `(Int & Any) => String`
- Transformations without any input can be found by a syntactic by name call e.g. `=> Int`
- A wildcard `_` can be used to indicate that we want to match any type in a given place e.g. `Long => Double => _`
- Types in the form of single letter e.g. `A` or a letter with a digit `X1` are automatically assumed to be type variables
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it should state here how to look for a type A rather then a type variable

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmmm, it's not possible ATM. Created an issue VirtusLab/Inkuire#199

julienrf
julienrf requested changes Jul 27, 2021
View reviewed changes
Copy link
Contributor

@julienrf julienrf left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for improving the documentation!

I found several typos, though.

Also, I think the structure of the page could be improved. Currently, I see sentences explaining how to use the feature, interleaved with sentences explaining how it works under the hood. Last, I don’t think we should talk about the roadmap here, I would rather put that information in the code repository. Here, we should focus on answering the following questions:

  • why is this feature useful?
  • how can people use it?
  • how can they contribute/help? (answer with a link to the code repository)

@KacperFKorban KacperFKorban requested a review from julienrf July 27, 2021 17:21
@KacperFKorban
Copy link
Member Author

@BarkingBad @julienrf Applied requested changes.

  • why is this feature useful?
  • how can people use it?

Changed the 'intro' a bit to make it more focused on those aspects. Waiting for further feedback 😄

julienrf
julienrf reviewed Jul 27, 2021
View reviewed changes
@KacperFKorban KacperFKorban requested a review from julienrf July 27, 2021 19:29
julienrf
julienrf reviewed Jul 28, 2021
View reviewed changes
@KacperFKorban KacperFKorban requested a review from julienrf July 28, 2021 08:04
julienrf
julienrf approved these changes Jul 28, 2021
View reviewed changes
Copy link
Contributor

@julienrf julienrf left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for your patience! Could you squash your commits before merging?

@KacperFKorban
Copy link
Member Author

Sure, done

@julienrf julienrf merged commit 3f52be2 into scala:main Jul 28, 2021
@KacperFKorban KacperFKorban deleted the inkuire-docs branch July 28, 2021 08:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@BarkingBad BarkingBad BarkingBad left review comments

@julienrf julienrf julienrf approved these changes

@romanowski romanowski romanowski approved these changes

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
4 participants
@KacperFKorban @BarkingBad @julienrf @romanowski