Documentation fixes and improvements #2289
Open
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
iwanders
commented
Jun 25, 2024
| @@ -134,7 +134,7 @@ fn from_raw_data<T: super::GgmlType + Send + Sync + 'static>( | |||
| super::QTensor::new(data, dims) | |||
| } | |||
|
|
|||
| /// Creates a [Tensor] from a raw GGML tensor. | |||
There was a problem hiding this comment.
137 | /// Creates a [Tensor] from a raw GGML tensor.
| ^^^^^^ no item named `Tensor` in scope
|
= help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`
= note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default
iwanders
commented
Jun 25, 2024
| @@ -1,6 +1,6 @@ | |||
| //! Support for the GGUF file format. | |||
| //! | |||
| //! Spec: https://github.com/philpax/ggml/blob/gguf-spec/docs/gguf.md | |||
There was a problem hiding this comment.
|
3 | //! Spec: https://github.com/philpax/ggml/blob/gguf-spec/docs/gguf.md
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ help: use an automatic link instead: `<https://github.com/philpax/ggml/blob/gguf-spec/docs/gguf.md>`
|
= note: bare URLs are not automatically turned into clickable links
= note: `#[warn(rustdoc::bare_urls)]` on by default
iwanders
commented
Jun 25, 2024
| @@ -19,6 +19,7 @@ | |||
| //! ``` | |||
| use candle::{Result, Tensor}; | |||
|
|
|||
| /// See the documentation for [`mod@super::linear`] for more information. | |||
There was a problem hiding this comment.
Rendered:
I didn't want to duplicate the module docs, it's not great, but it helps people find the actual docs.
iwanders
commented
Jun 25, 2024
| @@ -76,6 +77,7 @@ pub fn linear_no_bias(in_dim: usize, out_dim: usize, vb: crate::VarBuilder) -> R | |||
| Ok(Linear::new(ws, None)) | |||
| } | |||
|
|
|||
| /// Create or initialize a new linear layer, bias depending on the argument. | |||
There was a problem hiding this comment.
This function was the only one in the module without a line of documentation. THe function just switches between the other two based on the bias boolean, so I just added this.
iwanders
commented
Jun 25, 2024
| /// of categories. This is expected to contain log probabilities. | ||
| /// * [target]: The ground truth labels as a tensor of u32 of dimension `N`. | ||
| /// * `target`: The ground truth labels as a tensor of u32 of dimension `N`. |
There was a problem hiding this comment.
These were all unresolved links:
warning: unresolved link to `target`
--> /home/ivor/Documents/Code/rust/playground_candle/candle/candle-nn/src/loss.rs:36:8
|
36 | /// * [target]: The ground truth labels as a tensor of u32 of dimension `N`.
| ^^^^^^ no item named `target` in scope
|
= help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`
There is no current official way to document function arguments, I followed rust-lang/rust#57525.
Rendered:
iwanders
commented
Jun 25, 2024
| @@ -497,7 +497,7 @@ impl<'a> VarBuilder<'a> { | |||
| /// | |||
| /// # Safety | |||
| /// | |||
| /// The unsafe is inherited from [`memmap2::MmapOptions`]. | |||
| /// The unsafe is inherited from [`candle::safetensors::MmapedSafetensors::multi`]. | |||
There was a problem hiding this comment.
--> /home/ivor/Documents/Code/rust/playground_candle/candle/candle-nn/src/var_builder.rs:500:40
|
500 | /// The unsafe is inherited from [`memmap2::MmapOptions`].
| ^^^^^^^^^^^^^^^^^^^^ no item named `memmap2` in scope
|
= note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default
Presumably a copy paste from the documentation of multi itself, changed to point at the reason why this function is unsafe.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
I ended up on the documentation page for Linear which surprisingly didn't have any documentation on what that layer does. Only after reading the code did I see that the documentation lives in the module itself.
To test my newly added link, I ended up building the documentation, which showed several other warnings that I address in this PR as well, I'll comment why changes were warranted throughout my PR after I file it.
Edit: Forgot to say, but with these changes the documentation builds cleanly.