Boo
  1. Boo
  2. BOO-72

pipeline step that generates monodoc documentation files

    Details

    • Type: New Feature New Feature
    • Status: Open Open
    • Priority: Major Major
    • Resolution: Unresolved
    • Affects Version/s: 0.9.1
    • Fix Version/s: 0.9.5
    • Component/s: Compiler
    • Labels:
      None
    • Testcase included:
      yes
    • Number of attachments :
      3
    1. BooDocumentStep.cs
      7 kB
      Arron Washington
    2. dodocs.boo
      4 kB
      Doug H
    3. NaturalDocumentationDraft4.pdf
      13 kB
      Doug H

      Activity

      Hide
      Doug H added a comment -

      Attached a quick sample that spits out xml from the doc strings. Needs more work, maybe a better design, plus conversion from boo to C# in order to be included with boo.

      Show
      Doug H added a comment - Attached a quick sample that spits out xml from the doc strings. Needs more work, maybe a better design, plus conversion from boo to C# in order to be included with boo.
      Hide
      Arron Washington added a comment -

      This file is a compiler step that introduces document tags for Boo's, uh, document strings. Its based on Doug's prototype and knows the following tokens:

      @param arg information
      @except arg information
      @seealso arg
      @summary information
      @remarks information
      @permission arg information
      @example information
      @returns information

      Basically, it follows the C#-style of document tags with the exception of "@except" (to keep in line with Boo's "except" stuff).

      Its very rough (ugly) and the regular expressions are brittle because I'm terrible at them.

      On the other hand, it works and produces .xml files that can be consumed by nDoc and Visual Studio properly.

      Comments, or people willing to nice-it-up?

      Show
      Arron Washington added a comment - This file is a compiler step that introduces document tags for Boo's, uh, document strings. Its based on Doug's prototype and knows the following tokens: @param arg information @except arg information @seealso arg @summary information @remarks information @permission arg information @example information @returns information Basically, it follows the C#-style of document tags with the exception of "@except" (to keep in line with Boo's "except" stuff). Its very rough (ugly) and the regular expressions are brittle because I'm terrible at them. On the other hand, it works and produces .xml files that can be consumed by nDoc and Visual Studio properly. Comments, or people willing to nice-it-up?
      Hide
      Sorin Ionescu added a comment -

      Why not live it like C#'s? You would not have to parse it yourself since you got System.Xml, and it will also be more readable.

      """
      <summary>This class does cool stuff.</summary>
      """
      class Foo:
      """
      <summary>This method does cool stuff</summary>
      <param name="Foo">Foo has somedata</param>
      """
      def DoCoolStuff(foo):
      pass

      Show
      Sorin Ionescu added a comment - Why not live it like C#'s? You would not have to parse it yourself since you got System.Xml, and it will also be more readable. """ <summary>This class does cool stuff.</summary> """ class Foo: """ <summary>This method does cool stuff</summary> <param name="Foo">Foo has somedata</param> """ def DoCoolStuff(foo): pass
      Hide
      Cedric Vivier added a comment - - edited

      I'd like to implement this.

      I suggest we support same xml syntax as in C#, however the actual <xml> tags in documentation nodes would be optional.

      In a similar way as the natural documentation idea, which looks way more booish, we can easily handle booml-like syntax that actually has a 1:1 relationship with the xmldoc syntax

      As such the two doc nodes below outputs the same result:

      def Add(a as int, b as int) as int:
      """
      <summary>
      Adds `a' and `b'.
      </summary>
      <param name="a">the left integer</param>
      <param name="b">the right integer</param>
      <returns>the result of the addition</returns>
      """
      	return a + b
      
      
      def Add(a as int, b as int) as int:
      """
      summary:
      	Adds `a' and `b'.
      param a: the left integer
      param b:
              the right integer
      returns: the result of the addition
      """
      	return a + b
      

      Opinions?

      Show
      Cedric Vivier added a comment - - edited I'd like to implement this. I suggest we support same xml syntax as in C#, however the actual <xml> tags in documentation nodes would be optional. In a similar way as the natural documentation idea, which looks way more booish, we can easily handle booml-like syntax that actually has a 1:1 relationship with the xmldoc syntax As such the two doc nodes below outputs the same result: def Add(a as int , b as int ) as int : """ <summary> Adds `a' and `b'. </summary> <param name= "a" >the left integer</param> <param name= "b" >the right integer</param> <returns>the result of the addition</returns> """ return a + b def Add(a as int , b as int ) as int : """ summary: Adds `a' and `b'. param a: the left integer param b: the right integer returns: the result of the addition """ return a + b Opinions?
      Hide
      Cedric Vivier added a comment -

      Additionally we'd have an optional warning to make the compiler issue erm..a warning on visible classes/members without documentation

      Show
      Cedric Vivier added a comment - Additionally we'd have an optional warning to make the compiler issue erm..a warning on visible classes/members without documentation

        People

        • Assignee:
          Cedric Vivier
          Reporter:
          Rodrigo B. de Oliveira
        • Votes:
          0 Vote for this issue
          Watchers:
          0 Start watching this issue

          Dates

          • Created:
            Updated: