search

ocaml / odoc

Documentation compiler for OCaml and Reason
Other
321 stars 88 forks source link

Odoc does not ignore tags where they don't make sense #575

Open jonludlam opened 3 years ago

jonludlam commented 3 years ago

e.g. [@param] tags on instance variables are rendered. See https://ocaml.org/releases/4.12/htmlman/ocamldoc.html#ss:ocamldoc-syntax for a more detailed description of the expected behaviour.

jyotibalodhi commented 3 years ago

Hello @jonludlam, I am Jyoti and I am an outreachy applicant this summer. I am interested in contributing to the odoc project. I have knowledge of HTML, CSS but I am still learning OCaml. Also, I have been working on a few issues in the ocaml.org project as mentioned in the project contribution information on the outreachy website. It would be great if you can let me know if there are issues matching my skill set here which I can work on, or I should just contribute to the ocaml.org project for me recording my contributions for odoc. Thanks in advance!! :)

jonludlam commented 3 years ago

Hi Jyoti, thanks for taking an interest! This particular issue is a good first issue in that it will require a reasonably good of knowledge of OCaml, but not too much of Odoc itself. As such, if you're not confident working with OCaml I'd suggest starting over on the ocaml.org project where there is currently a lot of activity targetted at people just getting started in the ecosystem, then this might be a good issue to tackle once you're familiar with the tooling and language. Good luck!

jyotibalodhi commented 3 years ago

Hi Jyoti, thanks for taking an interest! This particular issue is a good first issue in that it will require a reasonably good of knowledge of OCaml, but not too much of Odoc itself. As such, if you're not confident working with OCaml I'd suggest starting over on the ocaml.org project where there is currently a lot of activity targetted at people just getting started in the ecosystem, then this might be a good issue to tackle once you're familiar with the tooling and language. Good luck!

Okay, Thank you so much! :)

github-actions[bot] commented 2 years ago

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. The main purpose of this is to keep the issue tracker focused to what is actively being worked on, so that the amount and variety of open yet inactive issues does not overwhelm contributors.

An issue closed as stale is not rejected — further discussion is welcome in its closed state, and it can be resurrected at any time. odoc maintainers regularly check issues that were closed as stale in the past, to see if the time is right to reopen and work on them again. PRs addressing issues closed as stale are as welcome as PRs for open issues. They will be given the same review attention, and any other help.

Julow commented 2 years ago

Instead of adding more special cases, what about accepting every tags instead ?

Currently, every tags have a different parsing, we would need a common syntax for every tags first. (perhaps two syntax, one specific to the existing tags that expect an identifier and a general syntax for the others).

jonludlam commented 2 years ago

Yes, I was also thinking along these lines. The more general type is the tag that allows markup - we could make is so that unrecognised tags were parsed like that.

Julow commented 2 years ago

We need this.

dangdennis commented 1 year ago

~I'll be spending time on this over the next set of weeks. Please do share any pointers or any existing work that's been done. I'll take this as my entry into odoc.~

Sorry I can’t pick this up anymore.