On 08/06/15 10:30, Daniel Kolesa wrote: > 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.
That one actually feels like a valid question/comment that I think we should address. It's useful for autocompletion too, because you sometimes want to know if you can use a function (based on your minimum supported version of the efl) or not. I believe Daniel answered the rest. -- Tom. ------------------------------------------------------------------------------ _______________________________________________ enlightenment-devel mailing list enlightenment-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
