Merge branch 'hb/optional_callbacks/OTP-11861'

* hb/optional_callbacks/OTP-11861:
  [edoc] Handle optional behaviour callbacks
  [syntax_tools] Let erl_syntax:concrete() accept the F/A syntax
  Introduce the attribute -optional_callbacks in the context of behaviours

2 files changed, 44 insertions, 18 deletions

diff --git a/lib/edoc/src/edoc_data.erl b/lib/edoc/src/edoc_data.erl
index f88ba05f4b..eceb5cb1bd 100644
--- a/lib/edoc/src/edoc_data.erl
+++ b/lib/edoc/src/edoc_data.erl
@@ -173,21 +173,34 @@ callbacks(Es, Module, Env, Opts) ->
 	lists:keymember(callback, 1, Module#module.attributes)
     of
 	true ->
-	    try (Module#module.name):behaviour_info(callbacks) of
-		Fs ->
-		    Fs1 = [{F,A} || {F,A} <- Fs, is_atom(F), is_integer(A)],
-		    if Fs1 =:= [] ->
-			    [];
-		       true ->
-			    [{callbacks,
-			      [callback(F, Env, Opts) || F <- Fs1]}]
-		    end
-	    catch
-		_:_ -> []
-	    end;
+            M = Module#module.name,
+            Fs = get_callback_functions(M, callbacks),
+            Os1 = get_callback_functions(M, optional_callbacks),
+            Fs1 = [FA || FA <- Fs, not lists:member(FA, Os1)],
+            Req = if Fs1 =:= [] ->
+                          [];
+                     true ->
+                          [{callbacks,
+                            [callback(FA, Env, Opts) || FA <- Fs1]}]
+                  end,
+            Opt = if Os1 =:= [] ->
+                          [];
+                     true ->
+                          [{optional_callbacks,
+                            [callback(FA, Env, Opts) || FA <- Os1]}]
+                  end,
+            Req ++ Opt;
 	false -> []
     end.
 
+get_callback_functions(M, Callbacks) ->
+    try
+        [FA || {F, A} = FA <- M:behaviour_info(Callbacks),
+               is_atom(F), is_integer(A), A >= 0]
+    catch
+        _:_ -> []
+    end.
+
 %% <!ELEMENT callback EMPTY>
 %% <!ATTLIST callback
 %%   name CDATA #REQUIRED
diff --git a/lib/edoc/src/edoc_layout.erl b/lib/edoc/src/edoc_layout.erl
index e164ff060f..87018af25a 100644
--- a/lib/edoc/src/edoc_layout.erl
+++ b/lib/edoc/src/edoc_layout.erl
@@ -701,6 +701,8 @@ deprecated(Es, S) ->
     end.
 
 behaviours(Es, Name) ->
+    CBs = get_content(callbacks, Es),
+    OCBs = get_content(optional_callbacks, Es),
     (case get_elem(behaviour, Es) of
 	 [] -> [];
 	 Es1 ->
@@ -709,13 +711,24 @@ behaviours(Es, Name) ->
 	      ?NL]
      end
      ++
-     case get_content(callbacks, Es) of
-	 [] -> [];
-	 Es1 ->
+     if CBs =:= [], OCBs =:= [] ->
+             [];
+	 true ->
+             Req = if CBs =:= [] ->
+                       [];
+                       true ->
+                           [br, " Required callback functions: "]
+                           ++ seq(fun callback/1, CBs, ["."])
+                   end,
+             Opt = if OCBs =:= [] ->
+                       [];
+                       true ->
+                           [br, " Optional callback functions: "]
+                           ++ seq(fun callback/1, OCBs, ["."])
+                   end,
 	     [{p, ([{b, ["This module defines the ", {tt, [Name]},
-			 " behaviour."]},
-		    br, " Required callback functions: "]
-		   ++ seq(fun callback/1, Es1, ["."]))},
+			 " behaviour."]}]
+                   ++ Req ++ Opt)},
 	      ?NL]
      end).