What's the deal with using 0 as success code? That is typical under O/S's such as Linux, but is that usually the case with Arduino/Energia libraries? I modeled mine around true/false so the if() block testing if a call succeeded was more intuitive.

Most of the functions return {"SL_FS_OK", 0} for success.

This is just a suggestion for increased consistency across functions.

Hmm. I was of the impression the rest of the WiFi library returned true/false for some miscellaneous functions, but the fact is upon examining the code I don't think it does, functions tend to return some sort of context-sensitive reply.

So I'll go ahead and switch the function calls to reply SL_FS_OK, and return the true errno value in error, including a few "synthetic errnos" I've added to reflect the SLFS library's own internal checks:

        {"SLFS_LIB_ERR_FILE_NOT_OPEN", -79},
        {"SLFS_LIB_ERR_FILE_OPEN_FOR_WRITE", -80},
        {"SLFS_LIB_ERR_FILE_OPEN_FOR_READ", -81},
        {"SLFS_LIB_ERR_FILE_ALREADY_OPEN", -82},

Also I noticed in this pullreq you're adding a lot of self-documenting comments here, can you give me a quick primer (or point me to one, looks like it's doxygen?) on how to add those manually? I've changed the code enough since this pullreq that it's not mergeable, but I can add the self-documenting comments myself and in fact would prefer to go down that route since you are able to produce a nice PDF from it all.

Looks like most of what I need to know is the list of available @ tags... although I can probably just infer that from your pullreq... but knowing what else is available might allow me to produce richer documentation (since I know what the intention is behind all the code).

As soon as I push the pull request, I was informed a new commit with significant changes had been added. Sorry for the conflicts, but you get the general idea.

Looks like most of what I need to know is the list of available @ tags... although I can probably just infer that from your pullreq... but knowing what else is available might allow me to produce richer documentation (since I know what the intention is behind all the code).

Yes, I'm using doxygen. There's a nice GUI front-end. It outputs HTML and Latex. The later is then converted into PDF using TeXShop.

As a matter of facts, doxygen is closely integrated into embedXcode with a handy short-cut for automatic template generation and a dedicated target.

I'm using all those tools on Mac OS X.

Nice! I am using Ubuntu Linux for all this so I'll try to get a toolchain going for doxygen there with the APT package manager.

http://www.stack.nl/~dimitri/doxygen/manual/commands.html has a lot of what I'm looking for.

@rei-vilo So I've added a bunch of comments to the SLFS.h, not complete by ANY means but I'm getting my feet wet with the doxygen code. I have thus far been testing it using doxywizard (a doxygen GUI) and examining the HTML output.

While there is no summary information yet, I am pleased with the type of output it's producing for function documentation. Can you give the current SLFS master a run through your embedXcode doxygen setup to see if there's anything I'm doing that's incompatible with embedXcode's features, and what the resulting PDF looks like so far? Just want to get your feedback on what I've done so far before I go too much further into documenting everything else (and then, if I'm making mistakes somewhere, having to go back and re-do it all...)

Great work! I'm glad you like doxygen. Of course, you should use the GUI front-end.

No major issues on the comments so far, except some functions have parameters still to be commented.

        ///
        /// @brief  <#Description#>
        /// @param  filename <#filename description#>
        /// @return <#return value description#>
        ///
        int32_t del(const uint8_t *filename);

Maybe delete would be better than del. Similarly, more concise text would be recommended to fit inside the bubble.

Here's the result: code-sense at work with Xcode:

• Tool-tip texts on the fly

Here's what happens with long documentation:

One more trick: change...

/// @n
///  GNU Lesser General Public License
/// @n
///  This library is free software; you can redistribute it and/or
/// @n
///  modify it under the terms of the GNU Lesser General Public
/// @n
///  License as published by the Free Software Foundation; either
/// @n
///  version 2.1 of the License, or (at your option) any later version.

for

/// @n
///  GNU Lesser General Public License
/// @n     This library is free software; you can redistribute it and/or
/// @n     modify it under the terms of the GNU Lesser General Public
/// @n     License as published by the Free Software Foundation; either
/// @n     version 2.1 of the License, or (at your option) any later version.

Final result is the same, but we gain readability on the source code.

Ok, how's the open() doc look now?

PS- I chose del() intentionally as I believe delete() is a reserved keyword in C++. I could also use "rm" or "remove" instead, what do you think?

Even if delete is already used, if will be always used as SerFlash.delete("my file") with SLFS.

That's the magic of objects!

@ref points to and requires @section.

Much better help bubble for open().

Ok I think I figured that out... just learned about \page and \section. So now the open opts have their own "Related" page, and \ref works right. Let me know if that works now.