On Mon, Jun 8, 2015 at 8:13 AM, Jean-Philippe André <j...@videolan.org> wrote: > 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.
They'd have to be modified either way, as the current docs in eo files are poorly written and need to be mostly rewritten. The syntaxes of what's written inside are not compatible. You never use doxygen tags within the [[...]] docs; they'll be generated automatically by the Eolian C generator. Anyway, they're better because you don't have to deal with comment style formatting (for example, the convention is to prefix each line in a comment with " * "). > Also the "no spaces preferred" rule does not seem to bring anything (except > laziness in the parser :-P)... There is a "no spaces preferred" rule because it looks better, but the parser will strip whitespace nevertheless, there is no laziness involved. > > - 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) They're not needed, as the @return is automatically inserted by the Eolian C generator. For example generation for this: https://git.enlightenment.org/core/efl.git/tree/src/tests/eolian/data/docs.eo makes this kind of output: http://codepad.org/RIYt5yxi > > - What about @since tags? No @since tags atm. That stuff would probably be documented on the wiki. The documentation in eo files is supposed to be bare, mostly for autocompletion etc. > > - 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 C generator automatically decides whether @brief is necessary. The general rule is that the new doc comments consist of summary and description, where summary is the first paragraph (typically one sentence) and description are all other paragraphs (paragraphs are separated by empty lines), and @brief is generated for the summary. > > >> 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) These will stay as they are, no changes to them. > > 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 D5 ------------------------------------------------------------------------------ _______________________________________________ enlightenment-devel mailing list enlightenment-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
