New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add Examples for class methods in Buffer #420

Merged

kentosugama merged 9 commits into master from buffer-examples

Oct 31, 2022

Contributor

kentosugama commented Oct 25, 2022 •

edited

Loading

Added examples to the class method documentations.
And ran new Motoko formatter over Buffer file.

kentosugama added 6 commits

October 24, 2022 17:18


          Examples for class methods in Buffer

c98a7c2


          Merge branch 'master' into buffer-examples

a75a711


          Merge branch 'master' into buffer-examples

46a36c4


          Merge branch 'master' into buffer-examples

838eb09


          run new motoko formatter

132792c


          Runnable example?

fee205a

crusso reviewed

View reviewed changes

src/Buffer.mo

		@@ -53,7 +60,7 @@ module {
		1;

Contributor

crusso Oct 31, 2022

curious, I wonder why the formatter didn't delete that semi after 1; but did delete the last semi in the else branch....

(Nothing to fix here)

Contributor Author

kentosugama Oct 31, 2022

Contributor

rvanasa Oct 31, 2022

This works as expected in the latest formatter version (always a trailing semicolon for multi-line blocks). Maybe it wasn't originally formatted? Otherwise, definitely let me know and I'll look into it.

crusso reviewed

View reviewed changes

Contributor

crusso left a comment •

edited

Loading

Great to add examples!
I think the fragments are not well-formed in isolation, right? That means a user can run the fragment on the page but gets a type error.

For those examples, it might be worth quoting them with

  !!!motoko no-repl

  !!!

instead. Here I've used !!! to represent ```.

There is actually a way to name fragments (like the initial import) and implicitly include them later using fancy block quote headers.

Then you might be able to drop some or all of those no-repl qualifiers and make more of the fragments executable.

Something like:

!!! motoko name=counter
actor Counter {

  var count = 0;

  public shared func inc() : async () { count += 1 };

  public shared func read() : async Nat { count };

  public shared func bump() : async Nat {
    count += 1;
    count;
  };
};
!!!

!!! motoko include=counter
let a : async Nat = Counter.read();
let n : Nat = await a;
!!!

(cribbed from https://github.com/dfinity/motoko/blob/master/doc/md/actors-async.md)
For an example, see https://internetcomputer.org/docs/current/developer-docs/build/cdks/motoko-dfinity/actors-async/#using-await-to-consume-async-futures

crusso reviewed

View reviewed changes

src/Buffer.mo Outdated

@@ @@ -23,6 +23,13 @@ @@
               /// exceeded. Further, when the size of the buffer shrinks to be less than 1/4th
               /// of the capacity, the underyling array is shrunk by a factor of 2.
               ///
+              /// Example:
+              /// ```motoko

Contributor

crusso Oct 31, 2022 •

edited

Loading

Suggested change

      
            /// ```motoko
          
            /// ```motoko name=common

crusso reviewed

View reviewed changes

src/Buffer.mo Outdated

@@ @@ -63,6 +70,11 @@ module { @@
                   /// Returns the current number of elements in the buffer.
                   ///
+                  /// Example:
+                  /// ```motoko

Contributor

crusso Oct 31, 2022 •

edited

Loading

Suggested change

      
                /// ```motoko
          
                /// ```motoko include=common

crusso reviewed

View reviewed changes

src/Buffer.mo Outdated

@@ @@ -71,6 +83,16 @@ module { @@
                   /// Adds a single element to the end of the buffer, doubling
                   /// the size of the array if capacity is exceeded.
                   ///
+                  /// Example:
+                  /// ```motoko

Contributor

crusso Oct 31, 2022 •

edited

Loading

Suggested change

      
                /// ```motoko
          
                /// ```motoko include=common

crusso reviewed

View reviewed changes

src/Buffer.mo Outdated

@@ @@ -84,6 +106,14 @@ module { @@
                   /// Returns the element at index `index`. Traps if  `index >= size`. Indexing is zero-based.
                   ///
+                  /// Example:
+                  /// ```motoko

Contributor

crusso Oct 31, 2022 •

edited

Loading

Suggested change

      
                /// ```motoko
          
                /// ```motoko include=common

crusso reviewed

View reviewed changes

src/Buffer.mo Outdated

@@ @@ -97,6 +127,14 @@ module { @@
                   /// Returns the element at index `index` as an option.
                   /// Returns `null` when `index >= size`. Indexing is zero-based.
                   ///
+                  /// Example:
+                  /// ```motoko

Contributor

crusso Oct 31, 2022

Suggested change

      
                /// ```motoko
          
                /// ```motoko include=common

crusso reviewed

View reviewed changes

src/Buffer.mo Outdated

@@ @@ -111,6 +149,14 @@ module { @@
                   /// Overwrites the current element at `index` with `element`. Traps if
                   /// `index` >= size. Indexing is zero-based.
                   ///
+                  /// Example:
+                  /// ```motoko

Contributor

crusso Oct 31, 2022

Suggested change

      
                /// ```motoko
          
                /// ```motoko include=common

crusso reviewed

View reviewed changes

src/Buffer.mo Outdated

@@ @@ -124,6 +170,17 @@ module { @@
                   /// Removes and returns the last item in the buffer or `null` if
                   /// the buffer is empty.
                   ///
+                  /// Example:
+                  /// ```motoko

Contributor

crusso Oct 31, 2022

Suggested change

      
                /// ```motoko
          
                /// ```motoko include=common

crusso reviewed

View reviewed changes

src/Buffer.mo Outdated

@@ @@ -155,6 +212,16 @@ module { @@
                   /// and might be a sign that you should consider a different data-structure
                   /// for your use case.
                   ///
+                  /// Example:
+                  /// ```motoko

Contributor

crusso Oct 31, 2022

Suggested change

      
                /// ```motoko
          
                /// ```motoko include=common

crusso reviewed

View reviewed changes

src/Buffer.mo Outdated

                   };
                   /// Resets the buffer. Capacity is set to 8.
                   ///
+                  /// Example:
+                  /// ```motoko

Contributor

crusso Oct 31, 2022

Suggested change

      
                /// ```motoko
          
                /// ```motoko include=common

crusso reviewed

View reviewed changes

src/Buffer.mo Outdated

@@ @@ -218,6 +294,15 @@ module { @@
                   /// The predicate is given both the index of the element and the element itself.
                   /// This may cause a downsizing of the array.
                   ///
+                  /// Example:
+                  /// ```motoko

Contributor

crusso Oct 31, 2022

Suggested change

      
                /// ```motoko
          
                /// ```motoko include=common

crusso reviewed

View reviewed changes

src/Buffer.mo Outdated

                     };
                     _size -= numRemoved;
                   };
                   /// Returns the capacity of the buffer (the length of the underlying array).
                   ///
+                  /// Example:
+                  /// ```motoko

Contributor

crusso Oct 31, 2022

Suggested change

      
                /// ```motoko
          
                /// ```motoko include=common

crusso reviewed

View reviewed changes

src/Buffer.mo Outdated

                   /// Runtime: O(1)
                   ///
                   /// Space: O(1)
                   public func capacity() : Nat = elements.size();
                   /// Changes the capacity to `capacity`. Traps if `capacity` < `size`.
                   ///
+                  /// ```motoko

Contributor

crusso Oct 31, 2022

Suggested change

      
                /// ```motoko
          
                /// ```motoko include=common

crusso reviewed

View reviewed changes

src/Buffer.mo Outdated

@@ @@ -311,6 +414,16 @@ module { @@
                   /// Adds all elements in buffer `b` to this buffer.
                   ///
+                  /// ```motoko

Contributor

crusso Oct 31, 2022

Suggested change

      
                /// ```motoko
          
                /// ```motoko include=common

crusso reviewed

View reviewed changes

src/Buffer.mo Outdated

@@ @@ -373,6 +493,15 @@ module { @@
                   /// Inserts `buffer2` at `index`, and shifts all elements to the right of
                   /// `index` over by size2. Traps if `index` is greater than size.
                   ///
+                  /// ```motoko

Contributor

crusso Oct 31, 2022

Suggested change

      
                /// ```motoko
          
                /// ```motoko include=common

crusso reviewed

View reviewed changes

src/Buffer.mo Outdated

@@ @@ -421,6 +550,17 @@ module { @@
                   /// Sorts the elements in the buffer according to `compare`.
                   /// Sort is deterministic, stable, and in-place.
                   ///
+                  /// ```motoko

Contributor

crusso Oct 31, 2022

Suggested change

      
                /// ```motoko
          
                /// ```motoko include=common

crusso reviewed

View reviewed changes

src/Buffer.mo Outdated

@@ @@ -499,6 +639,19 @@ module { @@
                   /// Iterator provides a single method `next()`, which returns
                   /// elements in order, or `null` when out of elements to iterate over.
                   ///
+                  /// ```motoko

Contributor

crusso Oct 31, 2022

Suggested change

      
                /// ```motoko
          
                /// ```motoko include=common

crusso reviewed

View reviewed changes

Contributor

crusso left a comment

Added some suggestion s on getting examples runnable (if you want to go there). Marking them all no-repl is fine too.

Contributor

crusso commented Oct 31, 2022

If you want to check the documentation examples work, your best bet might be to make a branch of motoko that references your base branch in nix/source.json and then do

nix-shell;
cd /doc; 
make base; 
make preview

or similar.
Bit of a pain, I admit.

kentosugama and others added 3 commits

October 31, 2022 12:41


          Runnable examples?

02d330e


          fix examples to run in interpeter

1ea1ab4


          fix example for insertBuffer

cb822a7

crusso approved these changes

View reviewed changes

Contributor

crusso left a comment

Nicely done!

kentosugama merged commit c2b221a into master

kentosugama deleted the buffer-examples branch

October 31, 2022 21:06

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet