Comments (5)
A bit unrelated maybe, but in README.md
cargo run --examples copy data/catalog.json tmp
doesn't work, but
cargo run --example copy data/catalog.json tmp
does.
from stac-rs.
In #81 I added warnings for documentation without examples. It only works with nightly
, so I ran it (e.g. on my mac) via rustup run nightly-x86_64-apple-darwin cargo doc
. This produces output like pasted below, which can be used to identify documentation without examples. Note that there may be false positives in there, i.e. code blocks that don't really need to have examples.
Missing code example output
--> src/layout.rs:44:1
|
44 | / /// Lay out a [Stac].
45 | | ///
46 | | /// The layout process consists of a couple steps:
47 | | ///
48 | | /// 1. Setting the `next_href` on all [Objects](Object) in the [Stac].
49 | | /// 2. Creating "structural" links (`parent`, `child`, `item`, and `root`) between all `Objects`.
| |_________________________________________________________________________________________________^
|
note: the lint level is defined here
--> src/lib.rs:155:9
|
155 | #![warn(rustdoc::missing_doc_code_examples)]
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
warning: missing code example in this documentation
--> src/layout.rs:125:1
|
125 | / impl Layout<BestPractices> {
126 | | /// Creates a new `Layout`.
127 | | ///
128 | | /// The root should be a directory, not a file name.
... |
143 | | }
144 | | }
| |_^
warning: missing code example in this documentation
--> src/layout.rs:146:1
|
146 | / impl<S: Strategy> Layout<S> {
147 | | /// Changes how [Hrefs](Href) are set.
148 | | ///
149 | | /// # Examples
... |
278 | | }
279 | | }
| |_^
warning: missing code example in this documentation
--> src/media_type.rs:1:1
|
1 | / //! [Media Types](https://en.wikipedia.org/wiki/Media_type) are a key element
2 | | //! that enables STAC to be a rich source of information for clients.
3 | | //!
4 | | //! The best practice is to use as specific of a media type as is possible (so
... |
7 | | //! IANA types as much as possible. The following table lists types that
8 | | //! commonly show up in STAC assets.
| |____________________________________^
warning: missing code example in this documentation
--> src/stac/walk.rs:123:1
|
123 | /// Walk
| ^^^^^^^^
warning: missing code example in this documentation
--> src/stac/walk.rs:125:5
|
125 | /// Options mut
| ^^^^^^^^^^^^^^^
warning: missing code example in this documentation
--> src/stac/walk.rs:196:1
|
196 | /// An iterator over a [Stac's](Stac) [Handles](Handle).
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
warning: missing code example in this documentation
--> src/stac/walk.rs:208:1
|
208 | /// An owned walk over a [Stac].
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
warning: missing code example in this documentation
--> src/stac/walk.rs:220:1
|
220 | /// Walk options
| ^^^^^^^^^^^^^^^^
warning: missing code example in this documentation
--> src/stac/walk.rs:227:1
|
227 | /// Walk strategy
| ^^^^^^^^^^^^^^^^^
warning: missing code example in this documentation
--> src/stac/walk.rs:238:1
|
238 | / impl<R: Read> Stac<R> {
239 | | /// Walk it
240 | | pub fn walk(
241 | | &mut self,
... |
267 | | }
268 | | }
| |_^
warning: missing code example in this documentation
--> src/stac/walk.rs:239:5
|
239 | /// Walk it
| ^^^^^^^^^^^
warning: missing code example in this documentation
--> src/stac/walk.rs:254:5
|
254 | /// Into walk it
| ^^^^^^^^^^^^^^^^
warning: missing code example in this documentation
--> src/stac/walk.rs:270:1
|
270 | / impl<'a, R: Read, F, T> BorrowedWalk<'a, R, F, T>
271 | | where
272 | | F: FnMut(&mut Stac<R>, Handle) -> Result<T>,
273 | | {
... |
285 | | }
286 | | }
| |_^
warning: missing code example in this documentation
--> src/stac/walk.rs:274:5
|
274 | /// Returns a new `Walk` with the provided `visit` function.
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
warning: missing code example in this documentation
--> src/stac/walk.rs:313:1
|
313 | / impl<R: Read, F, T> OwnedWalk<R, F, T>
314 | | where
315 | | F: FnMut(&mut Stac<R>, Handle) -> Result<T>,
316 | | {
... |
328 | | }
329 | | }
| |_^
warning: missing code example in this documentation
--> src/stac/walk.rs:317:5
|
317 | /// Returns a new `Walk` with the provided `visit` function.
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
warning: missing code example in this documentation
--> src/stac/mod.rs:134:1
|
134 | / /// A pointer to an [Object] in a [Stac] tree.
135 | | ///
136 | | /// Handles can only be used on the `Stac` that produced them. Using a `Handle`
137 | | /// on a different `Stac` is undefined behavior.
| |________________________________________________^
warning: missing code example in this documentation
--> src/stac/mod.rs:150:1
|
150 | / impl Stac<Reader> {
151 | | /// Creates a new `Stac` with the provided object and configured to use
152 | | /// [Reader].
153 | | ///
... |
181 | | }
182 | | }
| |_^
warning: missing code example in this documentation
--> src/stac/mod.rs:184:1
|
184 | / impl<R: Read> Stac<R> {
185 | | /// Creates a new `Stac` from the [Object] and [Read].
186 | | ///
187 | | /// Returns a tuple of the `Stac` and the [Handle] to that object.
... |
646 | | }
647 | | }
| |_^
warning: missing code example in this documentation
--> src/stac/mod.rs:529:5
|
529 | /// Takes the [Href] from the [Object].
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
from stac-rs.
Thanks!
from stac-rs.
https://doc.rust-lang.org/rustdoc/how-to-write-documentation.html#documenting-components provides the recommended structure for component documentation.
from stac-rs.
A question, the render
method seems to have a documentation page here already: https://docs.rs/stac/latest/stac/layout/struct.Layout.html#method.render
What is to be added to complete documentation examples here?
from stac-rs.
Related Issues (20)
- Fix leftover unimplemented in download
- Add release workflow that includes CLI builds
- Download item collections
- Improve stac-async documentation
- Add Cargo.lock for stac-cli HOT 1
- Collection download doesn't work HOT 1
- `ApiClient::items` documentation refers to `search`
- Best practices link 404s HOT 2
- Support 3D bounding boxes
- Bad error message in validation
- Add Python bindings
- Add common metadata fields
- Support `s3` hrefs in stac-async HOT 1
- Make stac-validate async
- Allow `stac-async` to compile and run och WebAssembly
- Allow constructing a `ApiClient` from a user-supplied `Client` HOT 1
- Take standard input to `stac validate`
- Add proj:shape, proj:transform, and proj:centroid to GDAL item creation
- Create a book
- Make creating `Items` and `Search` easier
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from stac-rs.