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 OTP versions in docs for "new" functions and modules #2044

Merged
merged 7 commits into from Dec 13, 2018

Conversation

Projects
None yet
6 participants
@sverker
Copy link
Contributor

commented Dec 5, 2018

The reference documentation will tell in which OTP version a function or module was first introduced.

For entire new modules, a "Since" headline is added at the top. Example:
http://erlang.org/~sverker/since/lib/stdlib-3.6/doc/html/rand.html

For functions, an OTP version is shown in the right margin. Example:
http://erlang.org/~sverker/since/erts-10.1.3/doc/html/erlang.html
(search for "OTP" a couple of times)

OTP versions older than R13B04 will not be shown.

You can browse all modules here:
http://erlang.org/~sverker/since/doc/man_index.html

@essen

This comment has been minimized.

Copy link
Contributor

commented Dec 5, 2018

Nice! That's useful. Orange though?

@sverker

This comment has been minimized.

Copy link
Contributor Author

commented Dec 5, 2018

@essen
For functions I thought the versions should have something that makes them stand out from the surrounding text, a possibly long function spec.

Maybe green is nicer, same color as the "Note" boxes.

@essen

This comment has been minimized.

Copy link
Contributor

commented Dec 5, 2018

For functions I thought the versions should have something that makes them stand out from the surrounding text, a possibly long function spec.

It does! Perhaps a bit too much.

Maybe green is nicer, same color as the "Note" boxes.

I'm sure @marianoguerra will want to pitch in. :-)

@michalmuskala

This comment has been minimized.

Copy link
Contributor

commented Dec 5, 2018

That's a great addition overall. It will make it simpler when working on libraries that need to support older versions.

For reference this is how similar information is displayed in the Elixir docs: https://hexdocs.pm/elixir/Date.html#add/2

@marianoguerra

This comment has been minimized.

Copy link
Contributor

commented Dec 5, 2018

Looks good!

Maybe for recent releases (2?) it has a more prominent color, since you should consider the compatibility implications of using it

for older releases it gets a softer color like grey, since it should be OK to use them, and someone who has to support older versions knows where to look.

@KennethL

This comment has been minimized.

Copy link
Contributor

commented Dec 5, 2018

The actual layout in the generated html is not in place yet. And is open for comments. A modified version is under construction.

@sverker sverker self-assigned this Dec 5, 2018

@crownedgrouse

This comment has been minimized.

Copy link
Contributor

commented Dec 6, 2018

Orange color should be used for deprecated functions and modules, maybe?

@sverker

This comment has been minimized.

Copy link
Contributor Author

commented Dec 10, 2018

Now a more discreet look.

@essen

This comment has been minimized.

Copy link
Contributor

commented Dec 10, 2018

Looks good!

sverker added some commits Nov 16, 2018

erl_docgen: Generate "since" OTP version in html
for <func><name> and <module> with "since" attribute.
erl_interface: Fix doc for return type 'struct hostent'
'*' is part of the return type, not the function name.

@sverker sverker force-pushed the sverker:sverker/add-since-doc/OTP-15460 branch from 7525fa0 to 20cc39d Dec 11, 2018

@sverker sverker added the testing label Dec 11, 2018

@sverker sverker added testing and removed testing labels Dec 11, 2018

sverker added some commits Dec 12, 2018

Fill in since for multi-clause functions in erlang.erl
The ones marked since="?" are unknown (but newer than R13B03)

monitor/2
port_info/2
process_flag/2
statistics/1
system_flag/2
system_info/1
trace_pattern/3

@sverker sverker merged commit 7c7a477 into erlang:maint Dec 13, 2018

2 checks passed

continuous-integration/travis-ci/pr The Travis CI build passed
Details
license/cla Contributor License Agreement is signed.
Details
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.