Improve BLE documentation

[Elara6331]

I have noticed, during my development of itd and infinitime, that the BLE documentation for InfiniTime is lacking. I had to spend over 2 hours scouring through Nordic documentation and InfiniTime source code just to find a couple UUIDs and a message format table. I decided to make some documentation. I posted it in my repo: docs.md. I wanted more people to be able to see it, so I merged it with the existing BLE docs and fixed some spelling and grammar mistakes.

[JF002]

Thanks! That looks good to me!
As you may have seen, I create a PR that adds a new Motion service (#754) and included documentation about this service in an additional file. This way, the main page is not cluttered with many details about all the services.

What do you think? Should we keep all the info in 1 page or create smaller pages about each service?

[Avamander]

I'm getting the feeling more and more than these paragraphs should just be JavaDoc-style inside the source code. This would reduce documentation maintenance burden and keeps relevant things tightly tied together.

[Elara6331]

Thanks! That looks good to me! As you may have seen, I create a PR that adds a new Motion service (#754) and included documentation about this service in an additional file. This way, the main page is not cluttered with many details about all the services.

What do you think? Should we keep all the info in 1 page or create smaller pages about each service?

It might be better to put them in separate files, but I think all the files should all be in a ble directory to make them easy to find.

[Elara6331]

I'm getting the feeling more and more than these paragraphs should just be JavaDoc-style inside the source code. This would reduce documentation maintenance burden and keeps relevant things tightly tied together.

The issue with that is it causes the same problem I had. I might not know precisely what I am looking for, in which case I would have to go through every file that looks like it might be related until I find it.

[Avamander]

I mean services are all very self contained and there's a few files to look at if you're interested in a single one. There's also search.

I don't think yours is a more common problem than documentation getting outdated when it's kept separate.

[Elara6331]

I mean services are all very self contained and there's a few files to look at if you're interested in a single one. There's also search.

I don't think yours is a more common problem than documentation getting outdated when it's kept separate.

That is a good point, but in the absence of something like godoc, it is very inconvenient to look for docs in the source code. I think some parts of this can be put in the source code, but some, like the DFU section, are too long to place the entire thing into the code.

[geekbozu]

I'm with avamander here, a large amount of this should be in the code and generated with some documentation generator that we can link to the planned #748
I love that its getting documented period however, and any an all is welcome. Since well none is worse :D

[JF002]

I suggest we move the discussion about how/where the developer documentation should be in #748.

In the meantime, I'll merge this PR as this project is missing a lot of documentation, and I wouldn't want this one to be forgotten.
We'll be able to move it to inline doc or to any other place later on ;)

Thanks again!