[erlang-patches] fm/file-operations

[Björn Gustavsson]

2010/5/19 Tuncer Ayaz <tuncer.ayaz@REDACTED>:

> I would prefer the documentation to be more in line with the existing
> text in file.xml, use the same order of advise values as in the
> original manpage and be less specific about the effect.

I also like your version better, except for a minor detail
which I have marked below.

Filipe, is this change OK for you?

> --- a/file.xml
> +++ b/file.xml
> @@ -69,16 +69,15 @@ time() = {{Year, Month, Day}, {Hour, Minute, Second}}
>         <v>Offset = int()</v>
>         <v>Length = int()</v>
>         <v>Advise = posix_file_advise()</v>
> -        <v>posix_file_advise() = normal | sequential | random | will_need
> -          | dont_need | no_reuse</v>
> +        <v>posix_file_advise() = normal | sequential | random | no_reuse
> +          | will_need | dont_need</v>
>         <v>Reason = ext_posix()</v>
>       </type>
>       <desc>
> -        <p>This function allows the Operating System to perform caching
> -           optimizations for accessing a file's data.</p>
> -        <p>This function is available only on POSIX compliant systems.
> -           For systems that are not POSIX compliant, this function has
> -           no effect when invoked.</p>
> +        <p><c>advise</c> can be used to announce an intention to access file

In the documentation, we include the arity when referring to a function.
Thus:

<p><c>advise/4</c> can be used to announce an intention to access file

> +          data in a specific pattern in the future, thus allowing the
> +          operating system to perform appropriate optimizations.</p>
> +        <p>On some platforms, this function might have no effect.</p>
>       </desc>
>     </func>
>     <func>
>

-- 
Björn Gustavsson, Erlang/OTP, Ericsson AB