Code Monkey home page Code Monkey logo

Comments (5)

pkopparla avatar pkopparla commented on July 26, 2024 1

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.

gadomski avatar gadomski commented on July 26, 2024 1

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.

pkopparla avatar pkopparla commented on July 26, 2024 1

Thanks!

from stac-rs.

gadomski avatar gadomski commented on July 26, 2024

https://doc.rust-lang.org/rustdoc/how-to-write-documentation.html#documenting-components provides the recommended structure for component documentation.

from stac-rs.

pkopparla avatar pkopparla commented on July 26, 2024

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)

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo 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.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.