Hello, On Sat, Jun 6, 2015 at 1:19 AM, Tom Hacohen <t...@osg.samsung.com> wrote:
> Hey, > > Daniel and I have been working recently on a new format for > documentation in Eo files. We want to use that in order to generate > basic documentation for methods/classes/parameters for use by IDEs and > in order to generate basic structure of documentation that will be > enhanced on the wiki with more usage tutorials, language specific > examples and etc. This means these documentations should be very short > and concise. No per method examples inline or anything like that. The > idea with the docs, as it is with the rest of Eolian is to be language > agnostic. > > Some things are done differently in different languages, but how the EFL > behaves remains the same. This means that most of the docs could be > written in a language-agnostic way with short tutorials per language > that translate the psuedocode examples into language specific examples. > Language specific tutorials are obviously still encouraged and will be > written with time. All of this will be done on the wiki, and not in .eo > files. > > We created a short wiki page that demonstrates the syntax we currently > use for docs in .eo files, you can see it here: > https://phab.enlightenment.org/w/eolian/docs/ > We use [[ as the starting delimiters and ]] as the ending delimiters. We > discourage the use of spaces between the delimiters and the text, so > this is a correct way of documenting a function: > [[This function does something]] > It's clear and clean, and will be even more clear with syntax highlighting. > The general idea of cleaning up the doc in the eo files sounds great. But I fail to understand why moving to a different syntax than what's currently there? - How are [[ ... ]] better than /*@ */ ? [[ ... ]] are just fine but this mean all the current eo files will have to be modified for something trivial. Also the "no spaces preferred" rule does not seem to bring anything (except laziness in the parser :-P)... - What about @return tags? Are they just not needed if the doc is properly written? (hint: I'm not convinced as I often look for the RETURN part of a manpage or another library's doc) - What about @since tags? - What about @brief tag equivalents? Is it the first line/paragraph separated by a blank line? (1-line descriptions are great for inline doc and summaries) > The link above includes all the examples and patterns we currently > support (and plan on supporting), so please read that page before you > comment here. > > We will update the wiki as we go with more clarifications and ideas, but > we would love to get your feedback and hear your thoughts. > > -- > Daniel and Tom. > Would the C++-style // and /* */ comments still be in the eo file? (but not generated as doc) Thanks a lot for initiating this effort. I'm looking forward to reading your comments and proposals :) -- Jean-Philippe André ------------------------------------------------------------------------------ _______________________________________________ enlightenment-devel mailing list enlightenment-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
