Skip to content
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 hidden attribute #950

Open
wants to merge 8 commits into
base: master
Choose a base branch
from
Open

Add hidden attribute #950

wants to merge 8 commits into from

Conversation

3Rafal
Copy link
Contributor

@3Rafal 3Rafal commented Apr 3, 2023

Implemented as specified in #578
I should probably add some documentation (and maybe more tests), but it would be better if someone could confirm that this implementation is correct beforehand.

@3Rafal 3Rafal marked this pull request as ready for review April 6, 2023 07:39
@3Rafal 3Rafal changed the title WIP: Add hidden attribute Add hidden attribute Apr 6, 2023
Copy link
Collaborator

@Julow Julow left a comment

Choose a reason for hiding this comment

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

The implementation looks good and the tests seem sufficient.

The [@@@hidden] seems unnecessary as we already have (**/**), which can always be used instead.
If we keep this feature, I suggest making "on" and "off" markers more explicit as there's room on the syntax:

[@@@hidden]

type a (* this is hidden *)

[@@@hidden]

type b (* this is visible *)

[@@@hidden on]

type a

[@@@hidden off]

type b

As @lpw25 said in #578 (comment), why use an attribute ([@@hidden]) instead of a tag ((** @hidden *)) ?
Odoc has other similar tags (the current bad name is "internal") like @canonical, @inline, etc...
Pinging @jonludlam as you decided on the syntax.

@Julow
Copy link
Collaborator

Julow commented Apr 7, 2023

Thanks a lot for contributing to Odoc :)

@3Rafal
Copy link
Contributor Author

3Rafal commented Apr 14, 2023

@Julow , if we want to use (**@hidden*) tag, then the change will involve odoc-parser. I can do a PR to parser which handles it. Do you think I can proceed, or should we wait for @jonludlam ?

@Julow
Copy link
Collaborator

Julow commented Apr 14, 2023

I don't know why we want the attribute but we also want the tag!

There's work to do on odoc-parser indeed. On Odoc's side, this kind of attributes are handled specifically here: https://github.com/ocaml/odoc/blob/master/src/model/semantics.mli#L14 the type handle_internal_tags signals what attributes are expected but @hidden is always expected so you don't need to hook into that and instead change the return value of the parsing functions.

@3Rafal
Copy link
Contributor Author

3Rafal commented Apr 14, 2023

I have created a PR for a new tag: ocaml-doc/odoc-parser#16

@panglesd panglesd mentioned this pull request Apr 20, 2023
@@ -96,6 +97,7 @@ let parse_attribute : Parsetree.attribute -> parsed_attribute option =
match load_payload attr_payload with
| Some p -> Some (`Doc p)
| None -> None)
| "hidden" | "ocaml.hidden" -> Some (`Hidden attr_loc)
Copy link
Collaborator

Choose a reason for hiding this comment

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

We discussed with @jonludlam and found that we don't need the attribute but prefer the tag instead. Do you mind opening a PR for that ?

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

Successfully merging this pull request may close these issues.

3 participants