cpu/esp8266: doc extended by gschorcht · Pull Request #10126 · RIOT-OS/RIOT

gschorcht · 2018-10-08T07:47:32Z

Contribution description

Documentation in cpu/esp8266/doc.txt was extended by section Erasing the Device which describes

how to erase the flash of the device, and
more important what to do after erasing the flash to get the device working again.

Testing procedure

It's just documentation.

gschorcht · 2018-12-26T18:36:51Z

@jia200x The disadvantage of handling board documentation as part of the code and as normal PRs is that it takes a lot of time before the changes become active. This PR is opened for almost 3 months.

Another problem I'm running into is that it becomes more and more difficult to merge the changes of this PR with changes of the documentation I had to make as part of other PRs 😟

aabadie

A few comments, mainly typos, duplicated words. I haven't checked the generated html.

I also think that the README.md file should be removed and only doc.txt be kept. This is the file used in the end by doxygen. Because as it is now, I see a very large and detailed documentation duplicated.

cpu/esp8266/README.md

aabadie · 2018-12-28T17:04:28Z

cpu/esp8266/README.md

+USEMODULE += esp_spiffs
+```
+
+Modules can be also be activated temporarily at the command line when calling the make command:


Extra be: Modules can also be activated...

aabadie · 2018-12-28T17:08:03Z

cpu/esp8266/README.md

-#endif
-```
-constructs, so it is possible to override them by defining them in front of these constructs.
+The board-specific configuration files ```board.h``` and ```periph_conf.h``` as well well as the driver parameter configuration files ```<driver>_params.h``` define the default configurations for peripherals and device driver modules. These are, for example, the GPIOs used, bus interfaces used or available bus speeds. Because there are many possible configurations and many different application requirements, these default configurations are usually only a compromise between different requirements.


Extra well

And I think this line could be split, but this comment would apply to large parts of this file.

I remember to our discussion regarding 80 characters per line also for documentation. These files were written before. I you insist on it, I can split the lines.

aabadie · 2018-12-28T17:12:46Z

cpu/esp8266/doc.txt


 </center><br>

+For example, to activate the a SPIFFS drive in on-board flash memory, the makefile of application has simply to add the ```esp_spiffs``` module to ```USEMODULE``` make variable:


Extra a copy pasted from the README.md. Just a thought: can we just keep one of these files ? (doc.txt)

README.md and doc.txt are identical. I use README.md to write the documentation to have immediate feedback in markdown viewer. It is quite tedious to write complex documentation for doxygen and execute make doc to see the results.

Using doc.txt is the new approach for board documentation. So, if only one file should be kept, it should be doc.txt 😟

I kept README.md for the moment so that you can track requested changes. I will remove it before squashing.

gschorcht · 2018-12-29T02:37:41Z

@aabadie Many thanks for your review.

aabadie

I built the documentation and checked the result: it's all ok.

ACK, please squash

gschorcht · 2019-01-09T15:04:48Z

@aabadie What do you think, should I remove README.md first? Yes, it is difficult to keep them consistent.

aabadie · 2019-01-09T15:09:03Z

should I remove README.md first? Yes, it is difficult to keep them consistent.

That would be better indeed.

gschorcht · 2019-01-10T07:45:20Z

@aabadie I would say that, the Codacy problem is a false positive. Can we merge inspite of it?

aabadie · 2019-01-10T20:16:17Z

Just in case @gschorcht, your last commit (71ff082) is removing the wrong README.md (in esp32 instead of esp8266) :)

The Codacy failure should be tackled if you fix this ;)

Documentation is generated by doxygen from doc.txt

gschorcht · 2019-01-11T00:57:04Z

@aabadie

your last commit (71ff082) is removing the wrong README.md (in esp32 instead of esp8266) :)

Ups 😎 Fixed.

aabadie · 2019-01-11T07:00:02Z

All green, let's merge!

gschorcht · 2019-01-11T12:42:18Z

@aabadie Thanks for your review.

miri64 requested a review from jia200x October 9, 2018 12:30

miri64 added Type: enhancement The issue suggests enhanceable parts / The PR enhances parts of the codebase / documentation Area: doc Area: Documentation Platform: ESP Platform: This PR/issue effects ESP-based platforms labels Oct 9, 2018

jia200x added the CI: ready for build If set, CI server will compile all applications for all available boards for the labeled PR label Oct 24, 2018

aabadie added this to the Release 2019.01 milestone Dec 3, 2018

gschorcht force-pushed the esp8266_doc branch from 832d46c to a80aecf Compare December 23, 2018 17:29

gschorcht mentioned this pull request Dec 27, 2018

cpu/esp8266: esp-now network device support #9917

Merged

aabadie requested changes Dec 28, 2018

View reviewed changes

aabadie approved these changes Jan 9, 2019

View reviewed changes

gschorcht added 2 commits January 9, 2019 16:03

cpu/esp8266: doc extended

323a3f9

cpu/esp8266: doxygen problem fix

0230d07

cpu/esp8266: doc fixes

fa0b4b8

gschorcht force-pushed the esp8266_doc branch from e247f13 to 71ff082 Compare January 9, 2019 16:17

gschorcht added CI: ready for build If set, CI server will compile all applications for all available boards for the labeled PR and removed CI: ready for build If set, CI server will compile all applications for all available boards for the labeled PR labels Jan 9, 2019

cpu/esp8266: README.md removed

c9d9d60

Documentation is generated by doxygen from doc.txt

gschorcht force-pushed the esp8266_doc branch from 71ff082 to c9d9d60 Compare January 10, 2019 23:50

aabadie merged commit afe3d67 into RIOT-OS:master Jan 11, 2019

gschorcht deleted the esp8266_doc branch January 11, 2019 12:42


		</center><br>

		For example, to activate the a SPIFFS drive in on-board flash memory, the makefile of application has simply to add the ```esp_spiffs``` module to ```USEMODULE``` make variable:

Conversation

gschorcht commented Oct 8, 2018

Contribution description

Testing procedure

Uh oh!

gschorcht commented Dec 26, 2018

Uh oh!

aabadie left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

aabadie Dec 28, 2018

Choose a reason for hiding this comment

Uh oh!

aabadie Dec 28, 2018

Choose a reason for hiding this comment

Uh oh!

aabadie Dec 28, 2018

Choose a reason for hiding this comment

Uh oh!

gschorcht Dec 29, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aabadie Dec 28, 2018

Choose a reason for hiding this comment

Uh oh!

gschorcht Dec 29, 2018

Choose a reason for hiding this comment

Uh oh!

gschorcht Dec 29, 2018

Choose a reason for hiding this comment

Uh oh!

gschorcht commented Dec 29, 2018

Uh oh!

aabadie left a comment

Choose a reason for hiding this comment

Uh oh!

gschorcht commented Jan 9, 2019

Uh oh!

aabadie commented Jan 9, 2019

Uh oh!

gschorcht commented Jan 10, 2019

Uh oh!

aabadie commented Jan 10, 2019

Uh oh!

gschorcht commented Jan 11, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

aabadie commented Jan 11, 2019

Uh oh!

gschorcht commented Jan 11, 2019

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

gschorcht Dec 29, 2018 •

edited

Loading

gschorcht commented Jan 11, 2019 •

edited

Loading