docs(flutter_weather): documentation feedback

felangel / bloc

A predictable state management library that helps implement the BLoC design pattern

https://bloclibrary.dev

MIT License

11.83k stars 3.4k forks source link

docs(flutter_weather): documentation feedback #2759

Closed jeroen-meijer closed 2 years ago

jeroen-meijer commented 3 years ago

Description

This issue is meant to log and keep track of feedback gathered from people who have used the Flutter Weather example, including comments about the documentation, the example code itself and any other aspects related to the project.

Feedback

In this section, I felt this was lacking.

This could be explained better.

Helper Folders are in a Local path
Sometimes its unclear where files should be located
weather_bloc_observer is never defined

Action Items

Update some_file.dart

Clarify text in this section

jeroen-meijer commented 3 years ago

Assigning @gvdvoort to provide feedback since he recently tried out this example.

jason-sch commented 3 years ago

I just tried out this example myself.

To view code coverage, I am instructed to run genhtml, which does not exist on my Windows box.
package:flutter_weather/weather/weather.dart is never defined. I correctly assumed it was supposed to be a barrel file.
WeatherCondition from weather_repository is used in ThemeCubit but not imported in theme_cubit.dart. Looking at the full source code, this appears to be a consequence of omitting the weather barrel file.
../../helpers/hydrated_bloc.dart is never defined.

Gene-Dana commented 3 years ago

Hey @jeroen-meijer, I believe this is the next document that is super important we review and make more clear. @felangel, perhaps this would be a great opportunity to detail the design from concept to completion here - what do you think?

jeroen-meijer commented 2 years ago

@Gene-Dana Thanks for the feedback! I agree this is one area of the documentation we want to significantly improve.

My apologies, but I'm unclear on the last part. Could you explain in more detail what you mean by the design from concept to completion? 🤔

chonghorizons commented 2 years ago

Felix mentioned wanting to get away from code snippets and to directly including of the code files. I wrote up a proposed styleguideline in this pull request. https://github.com/felangel/bloc/pull/3056/files #3056

I also wrote some tooling to auto-generate MD files and include statements. This helps with the "X file is missing from tutorial" comments above. How? Here's how:

Get a list of all the dart files
Generate the one-line for to include each file
Copy and paste the one-liners into the tutorial.

By doing this, this ensures there is complete file coverage in tutorials.

PS. I'm writing a lot because I'm trying to do some big doc cleanup. Feel free to ignore this if it's not useful.

felangel commented 2 years ago

Closing this since we already did a pass at updating examples and docs. Feel free to create new, specific issues for particular areas of improvement 👍