Replace EDoc-issued <tt> elements with <code> (in generated HTML)
#7643
Conversation
CT Test Results 2 files 13 suites 4m 41s ⏱️ Results for commit 901a320. ♻️ This comment has been updated with latest results. To speed up review, make sure that you have read Contributing to Erlang/OTP and that all checks pass. See the TESTING and DEVELOPMENT HowTo guides for details about how to run test locally. Artifacts// Erlang/OTP Github Action Bot |
garazdawi
added
testing
|
Thanks for this PR. I think we can make it target maint so that the docs and generation is updated as soon as possible.
|
|
Thanks for looking at this, @garazdawi.
Sure. My goal (initially) wasn't to remove it from OTP 😄 (even though I mention it as a possibility), but the documentation alone. Given your comment, maybe we could at least mark it as deprecated in the documentation (?) That'd be for another PR, though. Edit: I've rebased on top of What about " |
This is context-dependant, so I used code everywhere which is what seem to make th most sense
e.g. [https://erlang.org] edoc is, funny enough, code backwards :-)
e.g. fn() -> 'end'.
e.g. %% @param Var The variable
% @throws 'Something'
e.g. %% @type myList(X). A special kind of lists ...
When no EDoc is actually present e.g. id(Var) -> Var.
e.g. % @type str() = string().
e.g. % @equiv sth(Var, [])
(just define a behavior module to see how it works in terms of output)
e.g. -behaviour(gen_server).
e.g. %% @author carlsson.richard@gmail.com [http://example.net/richardc/]
paulo-ferraz-oliveira
force-pushed
the
feature/edoc-code-for-tt
branch
from
50004cc
to
901a320
Compare
sure, please do that. |
|
I'll do that in a subsequent pull request, then, to not have scope creep 😄 |
garazdawi
added
testing
|
Thanks! |
|
Thank you, Lukas. I'll get on the other one 👍 |
Motivation
Erlang EDoc's External links mentions
<a href="http://www.w3c.org/"><tt>http://www.w3c.org/</tt></a>.Via jelly-beam/rebar3_ex_doc#66 I found
<tt>is "deprecated" ("some browsers might still support it, it may have already been removed from the relevant web standards") and this has even been addressed in at least one commit in this repository.This pull request attempts at completely moving away from
<tt>in the scope of EDoc, to use semantic equivalents, all<code>. (I specifically mention this scope, because a fewttwill still remain in other parts of the doc - if you want I can also pull request to remove those).Other considerations
During this, I understood
@typeis deprecated in favor of-type. Should I make a new pull request to get rid of mentions to@typefrom the documentation? The code can also be scheduled for hard deprecation (I don't know when that warning was introduced) or simply removed (if it's there for more than 3 versions) and documented as a potential backward incompatibility.I separated this into several commits because I wanted to test changes as I went but I can easily squash them if need be.
Edit: I'm not
surethis should targetmaint(?) but it seems we can live a while longer with something that: a. is working still, b. has already been deprecated for a while.