Skip to content
Projects
Groups
Snippets
Help
Loading...
Help
Submit feedback
Sign in
Toggle navigation
F
Front-End
Project
Project
Details
Activity
Releases
Cycle Analytics
Repository
Repository
Files
Commits
Branches
Tags
Contributors
Graph
Compare
Charts
Issues
0
Issues
0
List
Board
Labels
Milestones
Merge Requests
0
Merge Requests
0
CI / CD
CI / CD
Pipelines
Jobs
Schedules
Charts
Wiki
Wiki
Snippets
Snippets
Members
Members
Collapse sidebar
Close sidebar
Activity
Graph
Charts
Create a new issue
Jobs
Commits
Issue Boards
Open sidebar
abdullh.alsoleman
Front-End
Commits
c6e45ffa
Unverified
Commit
c6e45ffa
authored
Feb 11, 2020
by
Greg Spencer
Committed by
GitHub
Feb 11, 2020
Browse files
Options
Browse Files
Download
Email Patches
Plain Diff
Updating snippets documentation README.md (#50483)
Updates the README file for snippets.
parent
8ef5e2f0
Changes
1
Hide whitespace changes
Inline
Side-by-side
Showing
1 changed file
with
84 additions
and
47 deletions
+84
-47
README.md
dev/snippets/README.md
+84
-47
No files found.
dev/snippets/README.md
View file @
c6e45ffa
# Dartdoc Generation
The Flutter API documentation contains code blocks that help provide
context or
a good starting point when learning to use any of Flutter's APIs.
The Flutter API documentation contains code blocks that help provide
context or
a good starting point when learning to use any of Flutter's APIs.
To generate these code blocks, Flutter uses dartdoc tools to turn documentation
in the source code into API documentation, as seen on https://api.flutter.dev/.
...
...
@@ -16,13 +16,23 @@ in the source code into API documentation, as seen on https://api.flutter.dev/.
## Types of code blocks
There
's two
kinds of code blocks.
There
are three
kinds of code blocks.
*
snippets, which are more or less context-free code snippets
that we
*
A
`snippet`
, which is a more or less context-free code snippet
that we
magically determine how to analyze, and
*
samples, which get placed into a full-fledged application, and can
be actually executed inline in the documentation using DartPad.
*
A
`dartpad`
sample, which gets placed into a full-fledged application, and can
be actually executed inline in the documentation on the web page using
DartPad.
*
A
`sample`
, which gets placed into a full-fledged application, but isn't
placed into DartPad in the documentation because it doesn't make sense to do
so.
Ideally every sample is a DartPad sample, but some samples don't have any visual
representation, and some just don't make sense that way (for example, sample
code for setting the system UI's notification area color on Android won't do
anything on the web).
### Snippet Tool
...
...
@@ -45,41 +55,39 @@ code. Here is an example of the code `snippet` tool in use:
/// {@end-tool}
```
This will generate sample code that can be copied to the clipboard and added
to
existing applications.
This will generate sample code that can be copied to the clipboard and added
to
existing applications.
This uses the skeleton for
[
snippet
](
config/skeletons/snippet.html
)
snippets
when generating the HTML to put into the Dart docs.
This uses the skeleton for
[
snippet
](
config/skeletons/snippet.html
)
snippets
when generating the HTML to put into the Dart docs.
#### Analysis
The
`../bots/analyze-sample-code.dart`
script finds code inside the
`@tool
snippet`
sections and uses the Dart analyzer to check them.
The
`../bots/analyze-sample-code.dart`
script finds code inside the
`@tool
snippet`
sections and uses the Dart analyzer to check them.
There are several kinds of sample code you can specify:
*
Constructor calls, typically showing what might exist in a build
method. These will be inserted into an assignment expression
assigning to a variable of type "dynamic" and followed by a
semicolon, for the purposes of analysis.
*
Constructor calls, typically showing what might exist in a build method. These
will be inserted into an assignment expression assigning to a variable of type
"dynamic" and followed by a semicolon, for the purposes of analysis.
*
Class definitions. These start with "class", and are analyzed
verbatim.
*
Class definitions. These start with "class", and are analyzed verbatim.
*
Other code. It gets included verbatim, though any line that says
`// ...`
is considered to separate the block into multiple blocks
to be processed
individually.
*
Other code. It gets included verbatim, though any line that says
`// ...`
is
considered to separate the block into multiple blocks to be processed
individually.
The above means that it's tricky to include verbatim imperative code
(e.g. a call to a method), since it won't be valid to have such code
at the top level. Instead, wrap it in a function or even a whole
class, or make it a valid
variable declaration.
The above means that it's tricky to include verbatim imperative code
(e.g. a
call to a method), since it won't be valid to have such code at the top level.
Instead, wrap it in a function or even a whole class, or make it a valid
variable declaration.
You can declare code that should be included in the analysis but not
shown in the API docs by adding a comment "// Examples can assume:" to
the file (usually at the top of the file, after the imports),
following by one or more commented-out lines of code. That code is
included verbatim in the analysis. For
example:
You can declare code that should be included in the analysis but not
shown in
the API docs by adding a comment "// Examples can assume:" to the file (usually
at the top of the file, after the imports), following by one or more
commented-out lines of code. That code is included verbatim in the analysis. For
example:
```
dart
// Examples can assume:
...
...
@@ -95,9 +103,12 @@ You can assume that the entire Flutter framework and most common
![
Code sample image
](
assets/code_sample.png
)
The code
`sample`
tool can expand sample code into full Flutter applications.
These sample applications can be directly copied and used to demonstrate the
API's functionality in a sample application:
The code
`sample`
and
`dartpad`
tools can expand sample code into full Flutter
applications. These sample applications can be directly copied and used to
demonstrate the API's functionality in a sample application, or used with the
`flutter create`
command to create a local project with the sample code. The
`dartpad`
samples are embedded into the API docs web page and are live
applications in the API documentation.
```
dart
/// {@tool sample --template=stateless_widget_material}
...
...
@@ -129,31 +140,34 @@ API's functionality in a sample application:
This uses the skeleton for
[
application
](
config/skeletons/sample.html
)
snippets.
Code
`sample`
also allow for quick Flutter app generation using the following command:
The
`sample`
and
`dartpad`
tools also allow for quick Flutter app generation
using the following command:
```
bash
flutter create
--sample
=[
directory.File.sampleNumber]
[
name_of_project_directory]
```
This command is displayed as part of the sample in the API docs.
#### Templates
In order to support showing an entire app when you click on the right tab of
the code sample UI, we have to be able to insert the
`sample`
block into the
template and instantiate the right parts.
In order to support showing an entire app when you click on the right tab of
the
code sample UI, we have to be able to insert the
`sample`
or
`dartpad`
block
into the
template and instantiate the right parts.
To do this, there is a
[
config/templates
](
config/templates
)
directory that
contains a list of templates. These templates represent an entire app that the
`sample`
can be placed into, basically a replacement for
`lib/main.dart`
in a
flutter app package.
`sample`
or
`dartpad`
can be placed into, basically a replacement for
`lib/main.dart`
in a
flutter app package.
For more information about how to create, use, or update templates, see
[
config/templates/README.md
](
config/templates/README.md
)
.
#### Analysis
The
`../bots/analyze-sample-code.dart`
script finds code inside the
`@tool sample`
sections and uses the Dart analyzer to check them
after applying the
specified template.
The
`../bots/analyze-sample-code.dart`
script finds code inside the
`@tool
sample`
sections and uses the Dart analyzer to check them after applying the
specified template.
## Skeletons
...
...
@@ -161,7 +175,8 @@ A skeleton (in relation to this tool) is an HTML template into which the Dart
code blocks and descriptions are interpolated.
There is currently one skeleton for
[
application
](
config/skeletons/sample.html
)
samples and one for
[
application
](
config/skeletons/sample.html
)
samples, one for
[
dartpad
](
config/skeletons/dartpad-sample.html
)
and one for
[
snippet
](
config/skeletons/snippet.html
)
code samples, but there could be more.
Skeletons use mustache notation (e.g.
`{{code}}`
) to mark where components will
...
...
@@ -184,8 +199,30 @@ that your code blocks are showing up correctly:
1.
Make an update to a code block or create a new code block.
2.
From the root directory, run
`./dev/bots/docs.sh`
. This should start
generating a local copy of the API documentation.
generating a local copy of the API documentation.
3.
Once complete, check
`./dev/docs/doc`
to check your API documentation. The
search bar will not work locally, so open
`./dev/docs/doc/index.html`
to
navigate through the documentation, or search
`./dev/docs/doc/flutter`
for your
page of interest.
search bar will not work locally, so open
`./dev/docs/doc/index.html`
to
navigate through the documentation, or search
`./dev/docs/doc/flutter`
for
your page of interest.
Note that generating the sample output will not allow you to run your code in
DartPad, because DartPad pulls the code it runs from the appropriate docs server
(master or stable).
Copy the generated code and paste it into a regular DartPad instance to test if
it runs in DartPad. To get the code that will be produced by your documentation
changes, run sample analysis locally (see the next section) and paste the output
into a DartPad at https://dartpad.dartlang.org.
## Running sample analysis locally
If all you want to do is analyze the sample code you have written locally, then
generating the entire docs output takes a long time.
Instead, you can run the analysis locally with this command from the Flutter root:
```
TMPDIR=/tmp bin/cache/dart-sdk/bin/dart dev/bots/analyze-sample-code.dart --temp=samples
```
This will analyze the samples, and leave the output in /tmp/samples
Write
Preview
Markdown
is supported
0%
Try again
or
attach a new file
Attach a file
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment