fix docs

demes/src/ffi.rs

@@ -404,13 +404,29 @@ pub unsafe extern "C" fn demes_graph_load_from_yaml(
 
 /// Initialize a [`Graph`] from a file.
 ///
+/// # Parameters
+///
+/// * `filename` - C-style string referring to a file containing YAML data.
+/// * `graph` - a mutable pointer to a pointer to a [`Graph`].
+/// * `error` - a mutatble reference/pointer to [`FFIError`].
+///
 /// # Returns
 ///
-/// * An initialized [`Graph`] upon success.
-/// * A null pointer upon error
-/// * A null pointer if `error` contains an error state,
-///   implying either an error has not been handled and/or
-///   it has not been cleared.
+/// * 0 upon success
+/// * non-zero upon error
+///
+/// # Side effects
+///
+/// Upon success:
+///
+/// * The pointee of `graph` points to a newly-allocated [`Graph`].
+///   This object must be freed via [`demes_graph_deallocate`].
+///
+/// Upon error:
+///
+/// * `error` will contain an error state.
+///   See [`demes_error_message`].
+/// * The pointee of `graph` will be a null pointer.
 ///
 /// # Error
 ///
@@ -424,11 +440,11 @@ pub unsafe extern "C" fn demes_graph_load_from_yaml(
 ///   [`CStr::from_ptr`](std::ffi::CStr::from_ptr)
 ///   must be upheld.
 /// * `error` must be a non-null pointer to a [`FFIError`]
+/// * `graph` must not by NULL.
 ///
-/// # Note
+/// # Notes
 ///
-/// The return value, if not NULL, **must** be freed via
-/// [`demes_graph_deallocate`], else a memory leak will occur.
+/// * Resource leaks may occur if the pointee of `graph` is not NULL.
 #[no_mangle]
 pub unsafe extern "C" fn demes_graph_load_from_file(
     // NOTE: it is very hard to test invalid c style strings.