Simon/Mbed Team,

Trying to grok my way through the best way of documenting my libraries and have some suggestions/questions.

First, using this as an example:- http://mbed.org/users/AjK/libraries/MODGPS/li1am1/docs/classGPS.html

The page starts with sections: "Public Types", "Public Member Functions", "Data Fields", "Protected Attributes" and then finally we reach "Detailed Description".

Imho it would be better if those first four sections came a at the end of the page and Detailed Desrciption was at the top of the page. The actual first part I want people to see is the handcrafted doxygen commenting that I did that starts by explaining the basics and then is followed by more in depth auto-generated sections. The first four parts seem to constitute more of an Index and I think they really should be below the parts I went to lengths to document which, at the moment, doesn't appear until you scroll down half way through the page.

Second question, do you have a sandbox to play in? At the moment I keep having to publish the new library and delete the old one to see the effects of doxygen comments I add/amend. I do have doxygen here and run it occasionally but it's output differs in layout to what the Mbed site produces. Pita having to keep publishing live libraries to see the little changes made.

regards,

--Andy

Hi Andy,

1) Doxygen actually links to the detailed description right at the top:

"GPS module. <More...>"

but it is not immediately intuitive to click that, I agree. We'll have a look at whether there are some layout tweaks that will render it better; I think your style is right.

2) We don't have a sandbox. My main idea is that, if people find the Doxygen stuff useful, it'll actually render it live in the compiler. So you could develop the documentation as you would the code, tweaking it until you are happy before publishing it. But we had no idea whether even the basic documentation would get used, so wanted to get "something" working rather than spending effort on a grand scheme that no-one used. So we'll monitor it for a bit, and if all is looking good we'll consider adding the live editing/rendering mode. I assume that would give you what you are after.

Simon

Andy,

I can look into changing the order of the sections in the documentation. However, the model as I see it at the moment is:

• The code API should documented in Doxygen since it's pretty good at that.

• All other documentation is in a wiki/notebook page, which is always going to be more flexible than doxygen for ad-hoc documentation.

• The wiki/notebook page is also the 'home' of the software in question - it links to the various bits of software that comprise the 'package'. For example your GPS module might have a dev version, a stable version and a 'hello world' program which acts as a a quick example.

Perhaps that 'model' should be explained somewhere!

As for a sandbox, you can publish it under a different name, with the 'add to my public profile' box unchecked, which will publish it quietly.

I'm interested in why you need to delete the previous versions of your library - the publishing system supports versioning, so the recommended method is just to keep publishing new versions, which builds up a nice development history of the program.

Also, for those who have integrated your library into their projects, publishing multiple versions of the same project will allow them to easily upgrade their version of your library - they get a little notice that the library has a newer version available.

Dan

Simon,

The idea of rendering in teh compiler would be good. I think if you monitor it you'll find not many using it because, like I found, it's not so easy to "test" documentation like it is to test code before releasing. I would love to see that but sounds like a lot of work for you guys to implement.

Dan,

If there's an intended documentation methodolgy in place perhaps you could enlighten us with, erm, some documentation :) lol

"I'm interested in why you need to delete the previous versions of your library" - because I don't want to have to publish an entire library just to see the changes made when I alter an @ingroup (or something equally as trivial). I'm use to using SVN and doxygen and I tend to "release" code when it's stable and by stable I mean code and documentation. The current way of doing things means I have to do a full release just to see minor changes to documentation. This isn't the same for code. I can tweak/debug code until it's stable here during development. Because the only way I have to "test" documentation is to publish. I'm not comfortable with a trillain little "releases" as I play around with teh documentation.

I wasn't aware of the notice given to library users of "new versions". Another reason for a sandbox! Imagine a trillion little notices due to "testing" documentation! Does this notice go out if I I uncheck the "Add to my profile" checkbox when I publish?

regards,

--Andy

Hi Andy,

I will have to create some documentation documentation!

Not wanting to waste resources on published libraries is commendable, but 44k is not a lot in the general scheme of things :) Agreed that ideally it would be a 'proper' versioning system (svn/git etc), and the idea is to move to that in the future.

The notices to users about new versions aren't per-release, it will just display an indication of the ability to upgrade when they look at the library within their program in the IDE. You can try it yourself by importing your own library and then releasing a new version.

One thing I forgot to mention in my last post is that in the upcoming version of the site, the program/library will contain a listing of which wikipages it is linked from, which will help tie things together.

Dan

Hi Dan,

I just tried a test. I did a publish of my MODGPS library without the checkbox ticked. This produced a listing in my profile    "(This is an unlisted program)"

However, it appears to have a side effect. If I go to the Compiler and search for libraries with "MOD" in it the previous "stable" release I did has gone. The previous version is also no longer listed in my profile.

The new release I did which is not public is fine and allows me to "test" doc changes. But it shouldn't remove the availability of "the last stable release" I published should it?

Shouldn't that previous version stay until I do another publcih with the checkbox ticked?

Andy