Skip to content

Commit

Permalink
docs: fix warnings and use warning note
Browse files Browse the repository at this point in the history
Fixes:
```
warning: redundant explicit link target
   --> binrw/src/../doc/attribute.md:120:85
    |
120 | | rw  | [`try_calc`](#calculations) | field | Like `calc`, but
returns a [`Result`](Result).
    |
--------  ^^^^^^ explicit target is redundant
    |
|
    |
because label contains path that resolves to same destination
    |
    = note: when a link's destination is not specified,
            the label is used to resolve intra-doc links
    = note: `#[warn(rustdoc::redundant_explicit_links)]` on by default
help: remove explicit link target
    |
120 | | rw  | [`try_calc`](#calculations) | field | Like `calc`, but
returns a [`Result`].
    |
~~~~~~~~~~

warning: redundant explicit link target
   --> binrw/src/../doc/attribute.md:121:92
    |
121 | | rw  | [`try_map`](#map) | all except unit variant | Like `map`,
but returns a [`Result`](Result).
    |
--------  ^^^^^^ explicit target is redundant
    |
|
    |
because label contains path that resolves to same destination
    |
    = note: when a link's destination is not specified,
            the label is used to resolve intra-doc links
help: remove explicit link target
    |
121 | | rw  | [`try_map`](#map) | all except unit variant | Like `map`,
but returns a [`Result`].
    |
~~~~~~~~~~

warning: redundant explicit link target
    --> binrw/src/../doc/attribute.md:1520:13
     |
1520 | [`Default`](core::default::Default) instead of reading data from
the reader:
     |  ---------  ^^^^^^^^^^^^^^^^^^^^^^ explicit target is redundant
     |  |
     |  because label contains path that resolves to same destination
     |
     = note: when a link's destination is not specified,
             the label is used to resolve intra-doc links
help: remove explicit link target
     |
1520 | [`Default`] instead of reading data from the reader:
     | ~~~~~~~~~~~

warning: `binrw` (lib doc) generated 3 warnings
```
  • Loading branch information
marxin committed Jun 7, 2024
1 parent c312ad3 commit 81a26dd
Showing 1 changed file with 11 additions and 3 deletions.
14 changes: 11 additions & 3 deletions binrw/doc/attribute.md
Original file line number Diff line number Diff line change
Expand Up @@ -117,8 +117,8 @@ Glossary of directives in binrw attributes (`#[br]`, `#[bw]`, `#[brw]`).
| rw | [`stream`](#stream-access-and-manipulation) | struct, non-unit enum, unit-like enum | Exposes the underlying <span class="br">read</span><span class="bw">write</span> stream.
| r | [`temp`](#temp) | field | Uses a field as a temporary variable. Only usable with the [`binread`](macro@crate::binread) attribute macro.
| r | [`try`](#try) | field | Tries to parse and stores the [`default`](core::default::Default) value for the type if parsing fails instead of returning an error.
| rw | [`try_calc`](#calculations) | field | Like `calc`, but returns a [`Result`](Result).
| rw | [`try_map`](#map) | all except unit variant | Like `map`, but returns a [`Result`](Result).
| rw | [`try_calc`](#calculations) | field | Like `calc`, but returns a [`Result`].
| rw | [`try_map`](#map) | all except unit variant | Like `map`, but returns a [`Result`].
| w | [`write_with`](#custom-parserswriters) | field | Specifies a custom function for writing a field.

[*]: #terminology
Expand Down Expand Up @@ -947,13 +947,17 @@ object.write(&mut output)

<div class="bw">

<div class="warning">

**These directives can only be used with [`binwrite`](macro@crate::binwrite).
They will not work with `#[derive(BinWrite)]`.**

**When using these directives, the `#[binwrite]` attribute must be placed
*before* other attributes like `#[derive(Debug)]`. Otherwise, the other
attributes will generate code that references non-existent fields, and
compilation will fail.**

</div>
</div>

The `calc` and `try_calc` directives compute the value of a field instead of
Expand Down Expand Up @@ -1517,7 +1521,7 @@ if let binrw::Error::NoVariantMatch { pos } = error {

For [`BinRead`](crate::BinRead), the `ignore` directive, and its alias
`default`, sets the value of the field to its
[`Default`](core::default::Default) instead of reading data from the reader:
[`Default`] instead of reading data from the reader:

```text
#[br(default)] or #[br(ignore)]
Expand Down Expand Up @@ -2663,13 +2667,17 @@ assert_eq!(out.into_inner(), b"\x01\x03\0\x04\x01");

# Temp

<div class="warning">

**This directive can only be used with [`binread`](macro@crate::binread). It
will not work with `#[derive(BinRead)]`.**

**When using `#[br(temp)]`, the `#[binread]` attribute must be placed *before*
other attributes like `#[derive(Debug)]`. Otherwise, the other attributes will
generate code that references non-existent fields, and compilation will fail.**

</div>

The `temp` directive causes a field to be treated as a temporary variable
instead of an actual field. The field will be removed from the struct
definition generated by [`binread`](macro@crate::binread):
Expand Down

0 comments on commit 81a26dd

Please sign in to comment.