Skip to content

Conversation

@KacperFKorban
Copy link
Member

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

Copy link
Contributor

@BarkingBadBarkingBad 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
MemberAuthor

Attached gif:
inkuire-1 0 0-M2_js_flatMap

Copy link
Contributor

@BarkingBadBarkingBad 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?

Copy link

@romanowskiromanowski 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.

- 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

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
MemberAuthor

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

Copy link
Contributor

@julienrfjulienrf 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
Copy link
MemberAuthor

@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 😄

Copy link
Contributor

@julienrfjulienrf 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
MemberAuthor

Sure, done

@julienrfjulienrf merged commit 3f52be2 into scala:mainJul 28, 2021
@KacperFKorbanKacperFKorban deleted the inkuire-docs branch July 28, 2021 08:32
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants

@KacperFKorban@BarkingBad@julienrf@romanowski