On Mon, Jun 8, 2015 at 6:45 PM, Tom Hacohen <t...@osg.samsung.com> wrote:
> 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 " * "). > That's kinda what I thought but I wanted to make sure this was the idea :) > > > >> 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. > Yeah, so it was a matter of taste: "it looks better" :-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) > > > > 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 > Yeah sorry I totally overlooked that. > > > >> > >> - 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. > I also think the @since information should be part of eo. Yep. Thanks. > > -- > Tom. > > > ------------------------------------------------------------------------------ > _______________________________________________ > enlightenment-devel mailing list > enlightenment-devel@lists.sourceforge.net > https://lists.sourceforge.net/lists/listinfo/enlightenment-devel > -- Jean-Philippe André ------------------------------------------------------------------------------ _______________________________________________ enlightenment-devel mailing list enlightenment-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
