No sir! Rock it. Thanks!
Yea, your ir-control/ir-control.h file could just say something like "There is no main module for this library, to use, pick the module that will work for your hardware and include that instead".
Iāve just published the eeprom library Iāve been working on - flashee-eeprom. I was trying to get one of my examples to compile, and needed some changes, which I pushed to github. The changes were in the spark-unit.h header. I tried removing the library from the app and re-adding it, but the changes were still not seen.
In desperation I added the library again, but now I have two copies of the library - the system doesnāt stop me adding a library twice with the same name!
I hope someone can clean up my mess!
@mdma, did you change the version number of the newer library in spark.json? If you did, the older library will disappear but it takes a few minutes. 
1 Like
Yep, I did change the version just in case that was the trigger for the update. I refreshed the IDE and now I see just one library. Cool.
1 Like
Iām trying to write docs for the library. It would be nice if the IDE could produce the API documentation from the source code ((e.g. doxygen). It could do this when the library is imported, and provide the docs link alongside the other links for that library (github, info).
While thereās already docs folder provided in the library spec, that means putting generated artefacts into the repo. Thatās pretty bad practice IMHO, and also a pain since each library writer has to then set up a doxygen build. Having this handled automatically by the IDE would increase library usability and quality, and lower the barrier to entry for library writers, not to mention bringing us one step closer to world peace.
2 Likes
Iāve seen doxygen done really well, and really poorly too. From some experiences Iāve had with it, it seems to get in the way of actually reading the code (maybe this was done poorly by an engineer I worked with). Even when it was done really well though, the documentation still was hard to navigate in my opinion. Would there still be a way to do markdown with doxygen? How would you handle the lengthy examples? Linking back to the code is definitely nice, and something we could easily do with the various Classes that already exist. Those links havenāt changed in forever so we should be able to rely upon them (without doxygen). Do you have any examples of open source software that uses doxygen that is done really well and is useful in your opinion?
Hereās an example I just found with googling - Iāve not seen the project before. But the docs looked good to me.
http://freedesktop.org/software/pulseaudio/doxygen/simple.html
A nice overview page. I clicked on the Simple API link. Then there was some code, and links to specific class methods under āBuffer Controlā. That cascading level of detail from overview to fine detail appeals to me - Iām not a fan of putting too much detail in README.md which quickly becomes hard to navigate and users can quickly become lost.
Of course, there will be cases where everything can be reasonably placed in the README.md file, and then linking directly to the code from there is a workable option. For small libraries I imagine that will be fine.
EDIT: You know, thinking about it. how can we link to an arbitrary class in source code? Weād have to continually update the line numbers in the hrefs in the documentation as changes are made to the source. Since each class in Doxygen is a separate file, linking is much easier.
Itās ok I guess, but it still makes my head hurt looking at it. The linking is really helpful, but I still wonder how intuitive that would be in terms of understanding the code organization. Just looking at that audio example I didnāt gleam anything useful just clicking through a bit, and then was lost in a sea of links.
I do agree, looking at the page for a long time made my head hurt. But afaik itās possible to specify stylesheets and make it look nicer than the default layout (although I know I would not spend the time on that, but maybe someone else would.)
I donāt have a strong affinity to doxygen, so anything else that can provide a nicely indexed view of the source code would be good. There are quite a few source code search engines, e.g. ohloh. Maybe just good indexing on the source is whatās neeeded?
That's what I was thinking... start there...
@Dave, one major shortcoming with importing libraries into the IDE is that the README is lost. This file typically contains vital information for using the library. Like github, this file should be prominent and easily displayed or simply display as the ācoverā page to any library. As it stands, all information in the README is lost unless someone knows to click on the github link to see it. Any thoughts?
4 Likes
Iāve noticed this too - the current āfront pageā is to open all the files in the library. That becomes unmanageable as the number of files grows - there are too many tabs, so the tab for each opened file becomes squeezed so that you canāt even see the full filename.
Itās then simpler to revert to clicking the invidiual filenames on the left to see the contents one by one.
+1 for importing the README.md and making that the default cover page.
2 Likes
+1 for me too. The README should be much more prominent. I like the idea of having it the default cover page. Seems like a straight forward change, added to backlog.
Regarding deeper source code specific documentation...
That is an interesting idea. I'm intrigued with the idea of taking ubiquity of Markdown with the power of Doxygen.
Yea, agreed. I'm thinking the first step here is to spec out some UI that displays documentation for each method or class in a library. Documentation content for each method would come by simply extracting a Markdown block that exists right before a method or class definition. This would be a big step forward. From there, if we wanted to get fancy, maybe we could come up with some Doxygen inspired syntaxes to support deeper semantic indexing of the code. Additionally, I think it'd be cool to have some Spark flavored markdown syntaxes to document things like Spark.variable, function, publish, and subscribe that would render example curl endpoints or something.
Thanks for the great discussion and ideas for improving the documentation.
I'll ping this thread when it ships or reach out to you individually to bounce ideas off of you as we start building this kind of thing.
2 Likes
Are there plans to break out most of the features currently in the core firmware into libraries?
E.g.
- I2C,
- EEPROM,
- TCP Client/Server,
- UDP Client/SErver,
- Wifi support
- Cloud protocol / OTA flashing
- Cloud variables/functions
Simply put, have the entire firmware modular so that unused components can be removed.
To make this user friendly, the IDE would start with all libraries included by default so users get the same experience as they do today. But advanced builders can turn off libraries that they donāt use, saving flash/ram space.
3 Likes
That would be a really neat feature!
Wow. An interesting idea with some huge implications. No, there are no plans to do this currently, but could see the benefit. I'm a little spooked to even begin thinking of how much work it would take to get there, 
. More than anything, before we could consider something like that, the library system itself would need to stabilize and support more complex workflows (with local + spark-cli compilation), library recursive dependency resolution would need to exist, automated testing tools + processes would need to mature and be built...but yea, super cool idea--something to keep on the backburner as we continue to refine core-firmware and the library system. Thanks for sharing!
Thereās an amount of work, but not insurmountable! I would break up the work into pieces:
- define symbols for each component and add conditional compilation to the current codebase. This allows development to continue, and provides delineating markers for components. For local builds,you can now already control what goes into the final executable by defining/undefining the symbol for each component.
- refactor 1: where a cpp or header file includes code from more than one module, split it so that each file contains code from only one module.
- refactor 2: now the sources are separate, reorganize files on disk into directories for each module
- testing: now the module sources are separate, testing becomes a lot easier, since we can include just the module, and then mock/fake the dependencies (includes etcā¦ and any other code the component depends on.)
- libraries/build system: integrate each module as a fully-fledged library in the build system (assuming transitive dependencies are enabled.)
- Then itās extending the online IDE to essentially treat each app also as a kind of module with dependencies.
By breaking it up like this, you get something useful at each step.
Regarding libraries and transitive dependencies, there are certainly plenty of existing software that does this, so no need to re-invent the wheel there. The first one that comes to mind is maven, and ivy.
1 Like
Yes @mdma !!! I follow you at every step of the way here. All that specificity makes the whole matter far less spooky indeed, cheers! 
Iād be curious hear what @zachary and @satishgn think about this concept and approach of breaking up the big features (like I2C, TCP, UDP, etc) of core firmware into libraries.
The primary benefits I see would be improved testability and modularity. The other benefit would be saving flash and RAM, but Iām skeptical of how great the savings would be; Iām pretty sure the arm-gcc compiler does a good job of optimizing unused symbols out of the resulting binary.