On Mon, Mar 10, 2014 at 7:48 AM, Christoph Reiter <[email protected]> wrote: > On Mon, Mar 10, 2014 at 4:27 AM, Simon Feltman <[email protected]> wrote: >> In terms of overrides having additional side effects beyond the >> intended GI API, I really hope we can deprecate those scenarios or >> additional arguments that invoke new/alternate behavior (like >> Gtk.MessageBox's "buttons" argument). It doesn't seem like there are >> very many of these cases and I'm not sure if the deprecations would help >> ease documentation or makes it more complex though. But I wouldn't >> mind leaving doc strings for deprecated functionality out granted >> usage of the function called as specified by a GI generated doc string >> works in a backwards compatible way (similarly I think we should >> ignore arguments/doc overrides for deprecated GObject initializers). > > I was mostly thinking of functions returning "(ok, result)" which gets > translated to "result or None". For other stuff, please keep in mind that > documentation can also be used for understanding old code, so I wouldn't > just ignore and hide them. I'd prefer deprecation warnings in the docstring > with instructions how to do it right in those cases.
For overrides which strip boolean results, one approach could be to extend the replacement key idea and have a specialized version: "%gi_doc_string_strip_boolean_result%". The strip_boolean_result() override helper could set this as the doc string on its returned function object. For cases where strip_boolean_result additionally raises, a "Raises:" annotation could be appended to to the doc string from the overrides side of things. In terms of deprecated overrides, I think what you've said sounds reasonable. For deprecated initializers, it should be fairly easy to generate informational doc strings within the init override helper (deprecated_init()), since it is passed all the relevant information. >> I was a bit overzealous with that statement. "should just work" is at >> least true in ipython standalone or integrated with eclipse/pydev >> (which is good enough for me at the moment). Eclipse nor Anjuta work >> for editor auto-completion with import hooks. At a cursory glance, >> Eclipse seems want to import the actual Python modules so there is >> some hope for this working in the editor. Anjuta uses python-rope >> which seems to use AST parsing and would be a more grave situation >> with import hooks. A little more reading of PEP302 reveals there was >> some talk about adding a "list_modules" method to the importer >> protocol which would potentially fix some of these problems, but it >> doesn't seem this has ever been added. > > Yeah, a possible solution is to create a fake package containing the whole > API (Google gives me fakegir [0], but I haven't tried it). I think IDE > integration deserves a page somewhere.. That is an interesting approach. >> The devhelp output wasn't really what I was expecting, which was >> style consistency of the html output. > > Style is fixable, it's just jinja templates. I could try to match the > "official" css, but that's then another thing to maintain and sync of > course. Disabling the sidebar and breadcrumbs should work for starters. I'm sure it is fixable one way or the other if we wanted to go there, but I think it is much less important than having accurate docs which include overrides. -Simon _______________________________________________ desktop-devel-list mailing list [email protected] https://mail.gnome.org/mailman/listinfo/desktop-devel-list
